Merge branch 'master' of http://82.157.175.59:3000/GenarrativeAI/Genarrative

2026-05-10 22:28:43 +08:00
parent 192accd796 54c2d6de47
commit d0a9348e72
46 changed files with 5894 additions and 341 deletions
@@ -16,6 +16,22 @@

 ---

+## 2026-05-10 运行态输入设备抽象层全项目通用化
+
+- 背景：拼图运行态接入 mocap 后，鼠标/触控和 mocap 各自维护输入逻辑会导致合并大块、拖拽语义和取消会话行为不一致；后续其他玩法也需要复用体感、摇杆、键盘等设备输入。
+- 决策：前端运行态输入统一通过 `src/services/input-devices/` 承接，设备适配层只输出 `press / move / release / tap / drop` 等通用语义和通用坐标；玩法组件自己解释目标对象、落点和业务动作，输入层不得写拼图等玩法专用规则。
+- 影响范围：拼图运行态鼠标/触控/mocap 输入、后续运行态设备接入、运行态输入技术文档与相关前端回归测试。
+- 验证方式：执行 `npm run test -- src\services\input-devices\runtimeDragInputController.test.ts`、`npm run test -- src\components\puzzle-runtime\PuzzleRuntimeShell.test.tsx`、`npm run typecheck` 和编码检查。
+- 关联文档：`docs/technical/RUNTIME_INPUT_DEVICE_ABSTRACTION_2026-05-10.md`、`docs/technical/PUZZLE_RUNTIME_FRONTEND_LOGIC_REHOME_2026-05-02.md`。
+
+## 2026-05-10 儿童动作热身关直接消费 mocap 手势流
+
+- 背景：儿童动作 Demo 的挥手、左右手挥动和跳跃阶段不能只依赖键鼠调试输入，否则真实硬件接入后会出现“能看到画面但动作不推进”的卡点。
+- 决策：热身关在 gesture 阶段直接接入 `useMocapInput`，通过本地 mocap WebSocket `/stream` 消费 `actions/action/gesture/gestures/event/name/type` 动作名，以及 `hands[]`、`leftHand/rightHand`、`left_hand/right_hand` 手部坐标；`wave_greeting`、`wave_left_hand`、`wave_right_hand` 和 `jump_once` 都可以由 mocap 包推进，同时保留键鼠作为本地调试兜底。
+- 影响范围：`src/services/useMocapInput.ts`、`src/components/child-motion-demo/ChildMotionWarmupDemo.tsx`、对应单测与热身关技术文档。
+- 验证方式：执行 `npx vitest run src/components/child-motion-demo/ChildMotionWarmupDemo.test.tsx src/components/child-motion-demo/childMotionWarmupModel.test.ts src/services/child-motion-demo/childMotionDebugInput.test.ts src/routing/appRoutes.test.ts`、`npx eslint ...`、`npm run typecheck`、`npm run check:encoding`，并确认 `http://127.0.0.1:3000/child-motion-demo` 与 `http://127.0.0.1:3100/healthz` 可访问。
+- 关联文档：`docs/technical/CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md`。
+
 ## 2026-05-09 GPT-image-2 图片生成统一迁移到 VectorEngine

 - 背景：仓库内 RPG、拼图、方洞和本地模板脚本的 GPT-image-2 生图此前依赖 APIMart 图片网关；团队要求参考 VectorEngine Apifox `api-448710071`，后续不再使用 APIMart 执行 GPT-image-2 图片生成。
@@ -43,6 +43,14 @@
 - 验证：提交前检查 `git diff -- .hermes`，确认没有密钥、会话记录或个人路径敏感信息。
 - 关联：`.hermes/README.md`。

+## 儿童动作 Demo 挥手阶段不推进先查 mocap 消费链路
+
+- 现象：`/child-motion-demo` 能打开摄像头画面，但到“打个招呼”或左右手挥动阶段时，真实硬件动作无法检测通过，只能用鼠标拖拽或键盘调试继续。
+- 原因：摄像头视频流只是舞台背景；如果热身关没有消费 `useMocapInput` 的动作名和手部坐标，就不会把硬件动作转换成热身状态机完成事件。
+- 处理：确认 `src/components/child-motion-demo/ChildMotionWarmupDemo.tsx` 在 `step.kind === 'gesture'` 时启用 `useMocapInput`；确认 `src/services/useMocapInput.ts` 能解析 `/stream` 包里的 `actions/action/gesture/gestures/event/name/type`、`hands[]`、`leftHand/rightHand`、`left_hand/right_hand`、左右手标记和 `open_palm/grab` 状态。热身关应由 mocap 推进，键鼠只作为本地调试兜底。
+- 验证：运行 `npx vitest run src\components\child-motion-demo\ChildMotionWarmupDemo.test.tsx`，并在本地硬件服务启动后进入 `/child-motion-demo` 实测招手、左右手挥动和跳跃阶段。
+- 关联：`src/services/useMocapInput.ts`、`src/components/child-motion-demo/ChildMotionWarmupDemo.tsx`、`docs/technical/CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md`。
+
 ## GPT-image-2 不再读 APIMart 图片配置

 - 现象：配置了 `APIMART_BASE_URL` / `APIMART_API_KEY` 后，RPG、拼图或方洞的 GPT-image-2 生图仍返回缺配置，或请求体里还出现 `official_fallback` / `image_urls`。
@@ -119,8 +127,8 @@

 - 现象：本地 `npm run dev` 因 `3101` 已占用、重复发布 SpacetimeDB wasm 编译太慢，或只想检查 `spacetime-module` 语法而被完整联调链路拖慢。
 - 原因：`npm run dev` 默认同时启动 SpacetimeDB standalone、发布 `server-rs/crates/spacetime-module`、启动 Rust `api-server`、主站 Vite 与后台 Vite；并非每个阶段都需要完整重启和重新发布。
- 处理：`npm run dev` 启动后会把实际 SpacetimeDB URL 记录到 `server-rs/.spacetimedb/local/data/dev-rust-spacetime-url`。下次启动即使没有传 `--skip-spacetime`，脚本也会先检查 `spacetime.pid` 对应进程和该 URL 是否在线；在线则直接复用现有宿主。确认需要新启动 SpacetimeDB 时，脚本先检测 `3101`，被占用则输出占用进程并选择最近可用端口，保证 publish 与 `api-server` 都连接同一个实际 SpacetimeDB URL。`api-server` 启动前也会检测 `8082` 并选择最近可用端口。Windows / Git Bash 下不要用 `tr/head/xargs` 管道读取 `spacetime.pid` 或 URL 记录，脚本应使用 Node 读取并短重试，避免 `tr: read error: Device or resource busy`；未修改 `spacetime-module` 时使用 `npm run dev -- --skip-publish`；只查模块语法时执行 `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`。
- 验证：`--skip-spacetime` 后脚本复用现有 `http://127.0.0.1:3101`；`3101` 或 `8082` 被其他进程占用时，脚本输出占用进程并使用最近可用端口；`--skip-publish` 后不再进入 publish 阶段；`cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml` 能完成 Rust 语法和类型检查。
+- 处理：`npm run dev` 启动后会把实际 SpacetimeDB URL 记录到 `server-rs/.spacetimedb/local/data/dev-rust-spacetime-url`。下次启动即使没有传 `--skip-spacetime`，脚本也会先检查 `spacetime.pid` 对应进程和该 URL 是否在线；在线则直接复用现有宿主。确认需要新启动 SpacetimeDB 时，脚本先检测 `3101`，被占用则输出占用进程并选择最近可用端口，保证 publish 与 `api-server` 都连接同一个实际 SpacetimeDB URL。`api-server` 启动前也会检测 `8082` 并选择最近可用端口。Windows / Git Bash 下不要用 `tr/head/xargs` 管道读取 `spacetime.pid` 或 URL 记录，脚本应使用 Node 读取并短重试，避免 `tr: read error: Device or resource busy`；未修改 `spacetime-module` 时使用 `npm run dev -- --skip-publish`；只查模块语法时执行 `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`。`npm run dev` 会在启动前检查 SpacetimeDB、api-server、主站 Vite、后台 Vite 端口，不可用时自动寻找后续可用端口，并把实际端口传给 publish、后端环境变量和前端代理目标。
+- 验证：`--skip-spacetime` 后脚本复用现有 `http://127.0.0.1:3101`；`3101` 或 `8082` 被其他进程占用时，脚本输出占用进程并使用最近可用端口；`--skip-publish` 后不再进入 publish 阶段；`cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml` 能完成 Rust 语法和类型检查。端口漂移时控制台会打印 `[dev:ports] ... 不可用，改用 ...`，后续 `[dev:rust] web/admin web/rust api/spacetime` 地址应与实际端口一致。
 - 关联：`docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md`、`scripts/dev-rust-stack.sh`。

 ## 本地 SpacetimeDB publish 401 可清本地库重发
@@ -191,6 +199,14 @@
 - 验证：`http://127.0.0.1:3000/api/auth/login-options` 返回至少 `{"availableLoginMethods":["phone","password"]}` 后，登录弹窗会恢复短信登录页签和“获取验证码”按钮。
 - 关联：`scripts/api-server-dev.mjs`、`scripts/api-server-maincloud.mjs`、`scripts/dev-rust-stack.sh`、`scripts/dev-web-rust.mjs`、`docs/technical/AUTH_LOGIN_OPTIONS_DESIGN_2026-04-21.md`。

+## 本地短信收不到验证码先查 provider
+
+- 现象：登录弹窗可以进入短信页签，但点击“获取验证码”后，手机没有收到短信。
+- 原因：本地 `.env.local` 里如果是 `SMS_AUTH_PROVIDER="mock"`，后端不会发真实短信，只会返回固定 mock 验证码；另外 `npm run api-server` 过去曾让 `.env` 覆盖 `.env.local`，导致本地真实短信配置被错误压回默认值。
+- 处理：真实短信联调时把 `.env.local` 的 `SMS_AUTH_PROVIDER` 显式设为 `aliyun`，然后重启 `api-server`；如果只想验证 UI 和账号链路，则保留 `mock` 并使用 `SMS_AUTH_MOCK_VERIFY_CODE`。
+- 验证：`GET /api/auth/login-options` 返回 `["phone","password"]`，`api-server` 日志里 `provider=aliyun` 才说明真实短信链路已生效。
+- 关联：`scripts/api-server-dev.mjs`、`docs/technical/AUTH_LOGIN_OPTIONS_DESIGN_2026-04-21.md`、`docs/technical/PHONE_SMS_REAL_PROVIDER_MANUAL_VERIFICATION_RUNBOOK_2026-04-23.md`。
+
 ## 手机验证码登录 500 先查短信 provider 语义

 - 现象：登录弹窗手机号验证码登录失败，浏览器看到 `POST /api/auth/phone/login 500`，后端日志里同时出现阿里云短信 `UNKNOWN`、`biz.FREQUENCY` 或 `check frequency failed`。
@@ -0,0 +1,127 @@
+---
+name: genarrative-dev-stack-port-routing
+short_description: 修改 Genarrative 本地 dev 启动端口、代理目标、端口冲突处理时使用。
+description: 在 Genarrative 中修改 npm run dev / npm run dev:rust / npm run dev:web 的本地启动端口、端口可用性探测、端口漂移、SpacetimeDB publish server、api-server 环境变量、Vite 代理目标和后台 admin-web 启动串联时使用。
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+metadata:
+  hermes:
+    tags: [Genarrative, dev-stack, 端口探测, Vite, api-server, SpacetimeDB, npm-run-dev]
+    related_skills: [genarrative-admin-backoffice]
+---
+
+# Genarrative 本地 dev 启动端口与代理目标串联流程
+
+用于维护 Genarrative 本地开发栈启动脚本，重点覆盖 `npm run dev` / `npm run dev:rust` / `npm run dev:web` 的端口检查、端口漂移和后续流程目标传递。
+
+## 适用场景
+
+- 修改 `scripts/dev-rust-stack.sh`、`scripts/dev-web-rust.mjs`、`scripts/dev-stack-port-utils.mjs`。
+- 处理 `3000`、`3101`、`3102`、`8082` 等端口被占用导致本地开发栈启动失败。
+- 排查 Vite 代理仍指向旧 api-server 端口、前端打开了旧 dev server、后台代理错配。
+- 调整 SpacetimeDB standalone、publish、Rust `api-server`、主站 Vite、后台 Vite 的启动顺序。
+- 修改本地联调文档或 `.hermes/shared-memory/pitfalls.md` 中的 dev 启动口径。
+
+## 当前端口职责
+
+默认优先端口：
+
+1. 主站 Vite：`3000`，对浏览器通常展示为 `http://127.0.0.1:<web-port>/`。
+2. Rust `api-server`：`8082`，健康检查为 `http://127.0.0.1:<api-port>/healthz`。
+3. SpacetimeDB standalone：`3101`，健康检查为 `http://127.0.0.1:<spacetime-port>/v1/ping`。
+4. 后台 Vite：`3102`，后台地址为 `http://127.0.0.1:<admin-web-port>/admin/`。
+
+端口不可用时，脚本会从优先端口开始向后寻找可用端口。后续流程必须以解析后的实际端口为准，不能继续使用默认端口。
+
+## 实现入口
+
+- `package.json`
+  - `dev` 和 `dev:rust`：执行 `node scripts/run-bash-script.mjs scripts/dev-rust-stack.sh`。
+  - `dev:web`：执行 `node scripts/dev-web-rust.mjs`。
+- `scripts/dev-stack-port-utils.mjs`
+  - `isPortAvailable(...)`：探测端口是否可监听。
+  - `findAvailablePort(...)`：从优先端口向后寻找可用端口，`0` 表示申请临时端口。
+  - `resolveDevStackPorts(...)`：一次性解析 SpacetimeDB、api-server、主站 Vite、后台 Vite 端口，并避免本次解析结果互相冲突。
+  - CLI 模式：`node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:3101 api:127.0.0.1:8082 web:0.0.0.0:3000 adminWeb:127.0.0.1:3102`。
+- `scripts/dev-rust-stack.sh`
+  - 解析 CLI 参数后，先计算 `API_TARGET_HOST` 与 `ADMIN_WEB_TARGET_HOST`。
+  - 调用 `resolve_dev_stack_ports` 覆盖 `SPACETIME_PORT`、`API_PORT`、`WEB_PORT`、`ADMIN_WEB_PORT`。
+  - 再构造 `SPACETIME_SERVER` 和 `RUST_SERVER_TARGET`。
+- `scripts/dev-web-rust.mjs`
+  - 单独启动主站前端时，也先用 `findAvailablePort` 检查 `WEB_PORT` / 默认 `3000`。
+
+## 必须保持的传递链路
+
+`npm run dev` / `npm run dev:rust` 中端口解析后，必须同步到以下位置：
+
+1. SpacetimeDB 启动：`spacetime start --listen-addr "${SPACETIME_HOST}:${SPACETIME_PORT}"`。
+2. SpacetimeDB 发布：`spacetime publish ... --server "${SPACETIME_SERVER}"`。
+3. Rust api-server：`GENARRATIVE_API_HOST`、`GENARRATIVE_API_PORT`、`GENARRATIVE_SPACETIME_SERVER_URL`、`GENARRATIVE_SPACETIME_DATABASE`。
+4. api-server 健康检查：`wait_for_api_server "${RUST_SERVER_TARGET}/healthz" ...`。
+5. 主站 Vite：`RUST_SERVER_TARGET`、`GENARRATIVE_RUNTIME_SERVER_TARGET`、`ADMIN_WEB_TARGET`、`ADMIN_WEB_PORT`、`--port=${WEB_PORT}`、`--host=${WEB_HOST}`。
+6. 后台 Vite：`ADMIN_API_TARGET`、`GENARRATIVE_API_TARGET`、`GENARRATIVE_API_PORT`、`--port=${ADMIN_WEB_PORT}`。
+7. 控制台日志：`[dev:ports]` 和 `[dev:rust] web/admin web/rust api/spacetime` 必须显示最终实际地址。
+
+如果只改了其中一段，通常会出现：浏览器打开的前端可用，但 `/api/*` 代理到旧端口；后台页面可用但后台 API 失败；SpacetimeDB 启动在新端口但 publish 仍发往旧端口。
+
+## 修改流程
+
+1. 先读当前脚本和文档：
+   - `scripts/dev-stack-port-utils.mjs`
+   - `scripts/dev-rust-stack.sh`
+   - `scripts/dev-web-rust.mjs`
+   - `docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md`
+   - `.hermes/shared-memory/pitfalls.md`
+2. 优先改公共端口工具，不要把端口探测逻辑复制到多个脚本。
+3. 对 Bash 脚本只做局部补丁，避免整文件重写导致中文注释或换行大面积变化。
+4. 修改 `dev-rust-stack.sh` 时确认变量顺序：
+   - 先有 `REPO_ROOT`。
+   - 再计算 `API_TARGET_HOST` / `ADMIN_WEB_TARGET_HOST`。
+   - 再调用端口解析工具。
+   - 再构造 `SPACETIME_SERVER` / `RUST_SERVER_TARGET`。
+5. 修改 `dev:web` 时不要自动改后端目标策略；`dev:web` 只负责主站 Vite 端口可用性与已有后端目标选择。
+6. 同步更新技术文档和团队共享记忆。
+
+## 测试与验证
+
+最小验证：
+
+```bash
+bash -n scripts/dev-rust-stack.sh
+npm run test -- scripts/dev-stack-port-utils.test.ts
+npm run check:encoding
+node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:0 api:127.0.0.1:0 web:0.0.0.0:0 adminWeb:127.0.0.1:0
+```
+
+端口冲突回归测试建议：
+
+1. 用测试或临时 Node server 占用某个优先端口。
+2. 调用 `findAvailablePort`，断言结果大于被占用端口。
+3. 调用 `resolveDevStackPorts`，断言四个结果互不相同。
+4. 如果实际启动完整栈，观察控制台：
+   - `[dev:ports] ... 不可用，改用 ...`
+   - `[dev:rust] rust api: http://...:<actual-api-port>`
+   - `[dev:rust] spacetime: http://...:<actual-spacetime-port>`
+   - 主站和后台 Vite 启动端口与日志一致。
+
+完整启动属于长驻进程。需要 smoke 时用 background 方式启动，并另开命令检查 `/healthz`、`/v1/ping` 和页面端口；不要等待 `npm run dev` 自然退出。
+
+## 常见坑
+
+1. **只让 Vite 自己漂移端口。** 这样终端可能出现可访问前端，但脚本和文档仍认为是 `3000`，后台目标或日志会错。
+2. **只改 SpacetimeDB start，不改 publish。** standalone 可能监听新端口，但 publish 仍连旧 `3101`。
+3. **只改 `GENARRATIVE_API_PORT`，不改 `RUST_SERVER_TARGET`。** api-server 已在新端口监听，但 Vite 代理仍打旧端口。
+4. **使用 `0.0.0.0` 作为浏览器访问地址。** 监听可以是 `0.0.0.0`，展示给用户和健康检查通常用 `127.0.0.1`。
+5. **端口探测和实际启动之间存在竞态。** 已经探测可用的端口仍可能被外部进程抢占；SpacetimeDB 启动后仍要解析实际监听地址，api-server 和 Vite 失败时要打印清晰日志。
+6. **运行全仓库 lint 误判。** 当前仓库可能有既有 lint 问题。验证本功能时优先运行定向测试、Bash 语法检查、编码检查，并在最终说明中区分既有 lint 失败与本次改动。
+
+## 验收清单
+
+- [ ] 端口工具有测试覆盖端口被占用和多端口互斥解析。
+- [ ] `dev-rust-stack.sh` 通过 `bash -n`。
+- [ ] `npm run dev` / `npm run dev:rust` 的 SpacetimeDB、publish、api-server、主站 Vite、后台 Vite 都使用实际端口。
+- [ ] `npm run dev:web` 在主站端口不可用时能切换到可用端口。
+- [ ] 文档同步更新 `docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md`。
+- [ ] 长期踩坑同步更新 `.hermes/shared-memory/pitfalls.md`。
+- [ ] 修改中文文件后运行 `npm run check:encoding`。
@@ -46,6 +46,7 @@
  - [$spacetimedb-concepts](.codex\\skills\\spacetimedb-concepts\\SKILL.md)
  - [$spacetimedb-typescript](.codex\\skills\\spacetimedb-typescript\\SKILL.md)
 - 涉及 `spacetime` CLI、发布、绑定生成、本地联调时，按 `spacetimedb-cli` 执行。
+- 涉及 `npm run dev` / `npm run dev:rust` / `npm run dev:web` 的端口探测、端口漂移、SpacetimeDB publish server、api-server 环境变量、Vite 代理目标或后台 dev 端口时，按 [`.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md`](.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md) 执行。
 - 涉及 `crates/spacetime-module` 的表、reducer、view、Rust API 使用时，按 `spacetimedb-rust` 与 `spacetimedb-concepts` 执行。
 - 涉及前端或 Node 侧的 SpacetimeDB TypeScript SDK、订阅、绑定使用时，按 `spacetimedb-typescript` 与 `spacetimedb-concepts` 执行。
 - 若仓库内旧实现或旧文档与这些 skill 冲突，先修正文档和方案，再继续编码。
@@ -0,0 +1,42 @@
+import {describe, expect, test} from 'vitest';
+
+import {
+  adminProfileTaskTrackingEventDefinitions,
+  adminTrackingEventDefinitions,
+  filterAdminProfileTaskTrackingEventDefinitions,
+  filterAdminTrackingEventDefinitions,
+  findAdminTrackingEventDefinition,
+} from './trackingEventDefinitions';
+
+describe('admin tracking event definitions', () => {
+  test('后台埋点筛选候选包含后端通用埋点清单', () => {
+    const keys = adminTrackingEventDefinitions.map((definition) => definition.key);
+
+    expect(keys.length).toBeGreaterThan(40);
+    expect(keys).toContain('daily_login');
+    expect(keys).toContain('auth_login_options_view');
+    expect(keys).toContain('task_center_view');
+    expect(keys).toContain('asset_upload_ticket_create');
+    expect(keys).toContain('creative_agent_route_success');
+    expect(keys).toContain('work_play_start');
+  });
+
+  test('任务配置候选只开放适合个人任务的事件', () => {
+    expect(adminProfileTaskTrackingEventDefinitions.map(({key}) => key)).toEqual([
+      'daily_login',
+    ]);
+    expect(filterAdminProfileTaskTrackingEventDefinitions('').map(({key}) => key)).toEqual([
+      'daily_login',
+    ]);
+  });
+
+  test('后台埋点筛选支持按中文名称和 key 搜索', () => {
+    expect(filterAdminTrackingEventDefinitions('上传票据').map(({key}) => key)).toEqual([
+      'asset_upload_ticket_create',
+    ]);
+    expect(filterAdminTrackingEventDefinitions('work_play').map(({key}) => key)).toEqual([
+      'work_play_start',
+    ]);
+    expect(findAdminTrackingEventDefinition(' daily_login ')?.title).toBe('每日登录');
+  });
+});
@@ -5,17 +5,400 @@ export interface AdminTrackingEventDefinition {
  title: string;
  scopeKind: TrackingScopeKind;
  remark: string;
+  taskConfigEligible?: boolean;
 }

 export const adminTrackingEventDefinitions: AdminTrackingEventDefinition[] = [
+  {
+    key: 'auth_login_options_view',
+    title: '登录方式查看',
+    scopeKind: 'site',
+    remark: '读取当前可用登录方式时记录，用于观察登录入口曝光。',
+  },
+  {
+    key: 'auth_phone_code_send',
+    title: '发送手机验证码',
+    scopeKind: 'site',
+    remark: '提交手机验证码发送请求成功后记录。',
+  },
  {
    key: 'daily_login',
    title: '每日登录',
    scopeKind: 'user',
-    remark: '用户打开任务中心时由后端幂等记录，用于每日登录任务进度校验。',
+    remark: '认证成功或 refresh 续期后由后端幂等记录，用于每日登录任务进度校验。',
+    taskConfigEligible: true,
+  },
+  {
+    key: 'auth_phone_login_success',
+    title: '手机号登录成功',
+    scopeKind: 'user',
+    remark: '手机号验证码登录成功后记录。',
+  },
+  {
+    key: 'auth_me_view',
+    title: '当前账号查看',
+    scopeKind: 'user',
+    remark: '读取当前登录账号信息成功后记录。',
+  },
+  {
+    key: 'auth_sessions_view',
+    title: '登录会话查看',
+    scopeKind: 'user',
+    remark: '读取当前账号登录会话列表成功后记录。',
+  },
+  {
+    key: 'auth_refresh_success',
+    title: '登录续期成功',
+    scopeKind: 'site',
+    remark: 'refresh cookie 续期成功后记录。',
+  },
+  {
+    key: 'auth_logout',
+    title: '退出登录',
+    scopeKind: 'user',
+    remark: '退出当前登录会话成功后记录。',
+  },
+  {
+    key: 'auth_logout_all',
+    title: '退出全部会话',
+    scopeKind: 'user',
+    remark: '退出全部登录会话成功后记录。',
+  },
+  {
+    key: 'auth_wechat_bind_phone_success',
+    title: '微信绑定手机成功',
+    scopeKind: 'user',
+    remark: '微信账号绑定手机号成功后记录。',
+  },
+  {
+    key: 'profile_identity_update',
+    title: '资料更新',
+    scopeKind: 'user',
+    remark: '用户资料更新成功后记录。',
+  },
+  {
+    key: 'profile_dashboard_view',
+    title: '个人看板查看',
+    scopeKind: 'user',
+    remark: '读取个人看板成功后记录。',
+  },
+  {
+    key: 'wallet_ledger_view',
+    title: '钱包流水查看',
+    scopeKind: 'user',
+    remark: '读取光点钱包流水成功后记录。',
+  },
+  {
+    key: 'recharge_center_view',
+    title: '充值中心查看',
+    scopeKind: 'user',
+    remark: '读取充值中心信息成功后记录。',
+  },
+  {
+    key: 'recharge_order_create',
+    title: '充值订单创建',
+    scopeKind: 'user',
+    remark: '创建充值订单成功后记录。',
+  },
+  {
+    key: 'feedback_submit',
+    title: '反馈提交',
+    scopeKind: 'user',
+    remark: '资料页反馈提交成功后记录。',
+  },
+  {
+    key: 'invite_center_view',
+    title: '邀请中心查看',
+    scopeKind: 'user',
+    remark: '读取邀请中心成功后记录。',
+  },
+  {
+    key: 'referral_invite_code_redeem',
+    title: '邀请码绑定',
+    scopeKind: 'user',
+    remark: '绑定推荐邀请码成功后记录。',
+  },
+  {
+    key: 'redeem_code_submit',
+    title: '兑换码提交',
+    scopeKind: 'user',
+    remark: '提交运营兑换码成功后记录。',
+  },
+  {
+    key: 'task_center_view',
+    title: '任务中心查看',
+    scopeKind: 'user',
+    remark: '读取个人任务中心成功后记录。',
+  },
+  {
+    key: 'task_reward_claim',
+    title: '任务奖励领取',
+    scopeKind: 'user',
+    remark: '领取个人任务奖励成功后记录。',
+  },
+  {
+    key: 'save_archive_list_view',
+    title: '存档列表查看',
+    scopeKind: 'user',
+    remark: '读取个人存档列表成功后记录。',
+  },
+  {
+    key: 'save_archive_detail_view',
+    title: '存档详情查看',
+    scopeKind: 'user',
+    remark: '读取个人存档详情成功后记录。',
+  },
+  {
+    key: 'browse_history_view',
+    title: '浏览历史查看',
+    scopeKind: 'user',
+    remark: '读取浏览历史成功后记录。',
+  },
+  {
+    key: 'browse_history_record',
+    title: '浏览历史写入',
+    scopeKind: 'user',
+    remark: '记录浏览历史成功后记录。',
+  },
+  {
+    key: 'browse_history_clear',
+    title: '浏览历史清空',
+    scopeKind: 'user',
+    remark: '清空浏览历史成功后记录。',
+  },
+  {
+    key: 'play_stats_view',
+    title: '游玩统计查看',
+    scopeKind: 'user',
+    remark: '读取个人游玩统计成功后记录。',
+  },
+  {
+    key: 'profile_analytics_metric_view',
+    title: '个人指标查看',
+    scopeKind: 'user',
+    remark: '读取个人埋点指标成功后记录。',
+  },
+  {
+    key: 'ai_task_create',
+    title: 'AI 任务创建',
+    scopeKind: 'user',
+    remark: '创建 AI 任务成功后记录。',
+  },
+  {
+    key: 'ai_task_start',
+    title: 'AI 任务启动',
+    scopeKind: 'user',
+    remark: '启动 AI 任务成功后记录。',
+  },
+  {
+    key: 'ai_task_stage_start',
+    title: 'AI 阶段启动',
+    scopeKind: 'user',
+    remark: '启动 AI 任务阶段成功后记录。',
+  },
+  {
+    key: 'ai_task_chunk_append',
+    title: 'AI 分片追加',
+    scopeKind: 'user',
+    remark: '追加 AI 文本分片成功后记录。',
+  },
+  {
+    key: 'ai_task_stage_complete',
+    title: 'AI 阶段完成',
+    scopeKind: 'user',
+    remark: '完成 AI 任务阶段成功后记录。',
+  },
+  {
+    key: 'ai_task_reference_attach',
+    title: 'AI 结果引用绑定',
+    scopeKind: 'user',
+    remark: '绑定 AI 结果引用成功后记录。',
+  },
+  {
+    key: 'ai_task_complete',
+    title: 'AI 任务完成',
+    scopeKind: 'user',
+    remark: '完成 AI 任务成功后记录。',
+  },
+  {
+    key: 'ai_task_fail',
+    title: 'AI 任务失败标记',
+    scopeKind: 'user',
+    remark: '标记 AI 任务失败成功后记录。',
+  },
+  {
+    key: 'ai_task_cancel',
+    title: 'AI 任务取消',
+    scopeKind: 'user',
+    remark: '取消 AI 任务成功后记录。',
+  },
+  {
+    key: 'asset_upload_ticket_create',
+    title: '资产上传票据创建',
+    scopeKind: 'user',
+    remark: '创建直传票据成功后记录，metadata 包含低敏资产定位字段。',
+  },
+  {
+    key: 'asset_sts_credentials_create',
+    title: '资产 STS 凭证创建',
+    scopeKind: 'user',
+    remark: '创建临时上传凭证成功后记录。',
+  },
+  {
+    key: 'asset_upload_confirm',
+    title: '资产上传确认',
+    scopeKind: 'user',
+    remark: '确认 OSS 对象为平台资产成功后记录。',
+  },
+  {
+    key: 'asset_bind',
+    title: '资产绑定',
+    scopeKind: 'user',
+    remark: '把平台资产绑定到业务实体成功后记录。',
+  },
+  {
+    key: 'asset_character_visual_generate',
+    title: '角色形象生成',
+    scopeKind: 'user',
+    remark: '角色主图生成请求成功后记录。',
+  },
+  {
+    key: 'asset_character_visual_publish',
+    title: '角色形象发布',
+    scopeKind: 'user',
+    remark: '角色主图发布成功后记录。',
+  },
+  {
+    key: 'asset_character_animation_generate',
+    title: '角色动画生成',
+    scopeKind: 'user',
+    remark: '角色动画生成请求成功后记录。',
+  },
+  {
+    key: 'asset_character_animation_publish',
+    title: '角色动画发布',
+    scopeKind: 'user',
+    remark: '角色动画发布成功后记录。',
+  },
+  {
+    key: 'asset_character_animation_import',
+    title: '角色动画视频导入',
+    scopeKind: 'user',
+    remark: '角色动画导入视频成功后记录。',
+  },
+  {
+    key: 'asset_character_workflow_cache_save',
+    title: '角色工作流缓存保存',
+    scopeKind: 'user',
+    remark: '保存角色工作流缓存成功后记录。',
+  },
+  {
+    key: 'asset_history_view',
+    title: '资产历史查看',
+    scopeKind: 'user',
+    remark: '读取资产历史成功后记录。',
+  },
+  {
+    key: 'llm_request',
+    title: 'LLM 请求',
+    scopeKind: 'user',
+    remark: '调用后端 LLM 门面成功后记录。',
+  },
+  {
+    key: 'speech_config_view',
+    title: '语音配置查看',
+    scopeKind: 'user',
+    remark: '读取语音配置成功后记录。',
+  },
+  {
+    key: 'asr_stream_start',
+    title: 'ASR 流启动',
+    scopeKind: 'user',
+    remark: '启动语音识别流成功后记录。',
+  },
+  {
+    key: 'tts_bidirection_start',
+    title: 'TTS 双向流启动',
+    scopeKind: 'user',
+    remark: '启动双向语音合成流成功后记录。',
+  },
+  {
+    key: 'tts_sse_start',
+    title: 'TTS SSE 启动',
+    scopeKind: 'user',
+    remark: '启动 SSE 语音合成成功后记录。',
+  },
+  {
+    key: 'runtime_settings_view',
+    title: '运行设置查看',
+    scopeKind: 'user',
+    remark: '读取运行设置成功后记录。',
+  },
+  {
+    key: 'runtime_settings_update',
+    title: '运行设置更新',
+    scopeKind: 'user',
+    remark: '更新运行设置成功后记录。',
+  },
+  {
+    key: 'runtime_snapshot_view',
+    title: '运行快照查看',
+    scopeKind: 'user',
+    remark: '读取运行快照成功后记录。',
+  },
+  {
+    key: 'runtime_snapshot_save',
+    title: '运行快照保存',
+    scopeKind: 'user',
+    remark: '保存运行快照成功后记录。',
+  },
+  {
+    key: 'runtime_snapshot_delete',
+    title: '运行快照删除',
+    scopeKind: 'user',
+    remark: '删除运行快照成功后记录。',
+  },
+  {
+    key: 'puzzle_route_success',
+    title: '拼图路由成功',
+    scopeKind: 'user',
+    remark: '拼图运行或创作接口成功响应后兜底记录；GET 入口可能按 site 统计。',
+  },
+  {
+    key: 'match3d_route_success',
+    title: '抓大鹅路由成功',
+    scopeKind: 'user',
+    remark: '抓大鹅创作或运行接口成功响应后兜底记录；GET 入口可能按 site 统计。',
+  },
+  {
+    key: 'square_hole_route_success',
+    title: '方洞路由成功',
+    scopeKind: 'user',
+    remark: '方洞创作或运行接口成功响应后兜底记录；GET 入口可能按 site 统计。',
+  },
+  {
+    key: 'custom_world_route_success',
+    title: '自定义世界路由成功',
+    scopeKind: 'user',
+    remark: '自定义世界运行接口成功响应后兜底记录；GET 入口可能按 site 统计。',
+  },
+  {
+    key: 'creative_agent_route_success',
+    title: '创意 Agent 路由成功',
+    scopeKind: 'user',
+    remark: '创意 Agent 接口成功响应后兜底记录；GET 入口可能按 site 统计。',
+  },
+  {
+    key: 'work_play_start',
+    title: '作品开始游玩',
+    scopeKind: 'work',
+    remark: '拼图、抓大鹅、方洞、自定义世界、大鱼吃小鱼、Visual Novel 正式开始游玩时记录。',
  },
 ];

+export const adminProfileTaskTrackingEventDefinitions =
+  adminTrackingEventDefinitions.filter((definition) => definition.taskConfigEligible);
+
 export function findAdminTrackingEventDefinition(eventKey: string) {
  const normalizedEventKey = eventKey.trim();
  return (
@@ -26,12 +409,26 @@ export function findAdminTrackingEventDefinition(eventKey: string) {
 }

 export function filterAdminTrackingEventDefinitions(query: string) {
+  return filterTrackingEventDefinitions(adminTrackingEventDefinitions, query);
+}
+
+export function filterAdminProfileTaskTrackingEventDefinitions(query: string) {
+  return filterTrackingEventDefinitions(
+    adminProfileTaskTrackingEventDefinitions,
+    query,
+  );
+}
+
+function filterTrackingEventDefinitions(
+  definitions: AdminTrackingEventDefinition[],
+  query: string,
+) {
  const normalizedQuery = query.trim().toLowerCase();
  if (!normalizedQuery) {
-    return adminTrackingEventDefinitions;
+    return definitions;
  }

-  return adminTrackingEventDefinitions.filter((definition) => {
+  return definitions.filter((definition) => {
    const haystack = [
      definition.key,
      definition.title,
@@ -13,7 +13,7 @@ import type {
 } from '../api/adminApiTypes';
 import {useAdminWriteConfirm} from '../components/useAdminWriteConfirm';
 import {
-  filterAdminTrackingEventDefinitions,
+  filterAdminProfileTaskTrackingEventDefinitions,
  findAdminTrackingEventDefinition,
 } from '../config/trackingEventDefinitions';
 import {handlePageError} from './pageUtils';
@@ -68,7 +68,7 @@ export function AdminTaskConfigPage({
    [eventKey],
  );
  const filteredEventDefinitions = useMemo(
-    () => filterAdminTrackingEventDefinitions(eventKeySearch),
+    () => filterAdminProfileTaskTrackingEventDefinitions(eventKeySearch),
    [eventKeySearch],
  );

@@ -16,6 +16,8 @@

 后续生产的该内容线模板和游戏关卡，都放置在“寓教于乐”独立标签下。

+该内容线当前只覆盖儿童动作识别 Demo 内容。后续创作环节需要继续对该板块内容做区分和独立管理，不把普通公开作品仅凭近似教育题材自动归入本板块。
+
 ## 2. 展示边界

 寓教于乐内容不直接展示在以下位置：
@@ -29,6 +31,8 @@

 寓教于乐内容只在“发现 / 寓教于乐”标签下展示。

+“寓教于乐”标签在发现页频道列表中放在最后，桌面端和移动端都显示。移动端访问该内容线的动作识别 Demo 时，需要提示横屏体验。
+
 ## 3. 开关规则

 该入口需要支持灵活开关。
@@ -43,13 +47,14 @@

 1. 发现页隐藏“寓教于乐”标签；
 2. 隐藏“寓教于乐”标签下内容；
-3. 该内容线内容不进入推荐、今日、分类、排行和搜索结果。
+3. 该内容线内容不进入推荐、今日、分类、排行和搜索结果；
+4. 该内容线内容完全不可见，公开作品搜索、作品号搜索直达、公开详情深链、浏览历史入口等平台公开入口都不能打开该内容。

 ## 4. 内容识别规则

 临时阶段使用作品标签识别寓教于乐内容。

-当公开作品标签中包含：
+当公开作品标签中存在一个精确等于以下文本的标签：

 ```text
 寓教于乐
@@ -57,6 +62,10 @@

 则该作品归入寓教于乐内容线。

+识别规则为精确匹配，不做包含匹配，不兼容空格、大小写变体或同义标签，例如“教育”“儿童教育”“动作教育”都不视为寓教于乐内容。
+
+关闭开关时，即使作品具备精确的“寓教于乐”标签，也不允许通过任何平台公开展示入口或搜索入口访问。
+
 ## 5. 技术落地边界

 本次只做前端入口和前端展示过滤，不新增后端接口。
@@ -87,3 +96,22 @@ no
 3. 带有“寓教于乐”标签的公开作品不进入推荐页。
 4. 带有“寓教于乐”标签的公开作品不进入发现页推荐、今日、分类、排行和搜索结果。
 5. 带有“寓教于乐”标签的公开作品只在“发现 / 寓教于乐”标签下展示。
+6. “寓教于乐”标签位于发现页频道列表最后，桌面端和移动端均可见。
+7. 开关关闭后，带有“寓教于乐”标签的公开作品不可通过作品号搜索、公开详情深链或浏览历史入口打开。
+8. 标签识别只接受精确等于“寓教于乐”的作品标签，近似标签不归入该内容线。
+
+## 7. 待补充事项
+
+“寓教于乐”标签下暂无内容时的空状态文案待定。落地时可先复用平台现有空状态组件，但不新增功能说明类长文案。
+
+## 8. 第 1-2 项工程落地状态
+
+第 1 项“发现页入口与过滤”和第 2 项“搜索 / 深链 / 历史入口拦截”已进入前端落地阶段，当前实现口径如下：
+
+1. 入口开关由 `VITE_ENABLE_EDUTAINMENT_ENTRY` 控制，默认开启，显式配置 `false`、`0`、`off`、`no` 时关闭。
+2. 内容识别集中在 `src/components/platform-entry/platformEdutainmentVisibility.ts`，只读取公开作品原始 `themeTags`，且只接受精确等于“寓教于乐”的标签。
+3. `src/components/rpg-entry/RpgEntryHomeView.tsx` 已在发现页频道末尾追加“寓教于乐”频道，并将该类作品从推荐、今日、分类、排行、搜索、本地搜索兜底和桌面推荐模块中过滤。
+4. `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx` 已复用同一过滤 helper，避免推荐运行态自动启动寓教于乐作品，并在公开详情、作品号直达和公开详情深链等公开入口保留不可见保护。
+5. 浏览历史入口会优先按当前公开作品集合匹配作品标签；匹配到“寓教于乐”作品且开关关闭时不再展示历史入口。
+6. `/child-motion-demo` 本地动作 Demo 直达路由也复用同一开关；开关关闭时不匹配独立 Demo 应用，回落到主站入口。
+7. 定向回归覆盖在 `src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`、`src/components/platform-entry/platformEdutainmentVisibility.test.ts` 和 `src/routing/appRoutes.test.ts`，包含频道顺序、开关关闭、普通列表过滤、搜索过滤、作品号直达拦截、Demo 直达路由拦截和精确标签识别。
@@ -72,7 +72,7 @@ GET /admin/api/tracking/events?eventKey=&userId=&scopeKind=&scopeId=&limit=

 页面能力：

-1. 顶部筛选区：Event Key、用户 ID、Scope Kind、Scope ID、刷新、导出 Excel。
+1. 顶部筛选区：Event Key、用户 ID、Scope Kind、Scope ID、刷新、导出 Excel。Event Key 候选来自后台前端的埋点定义注册表，需覆盖 `BACKEND_TRACKING_EVENT_COVERAGE_2026-05-09.md` 中已接入的通用埋点事件，不能只保留 `daily_login`。
 2. 列表区：移动端可横向滚动，桌面端表格展示。
 3. 详情区：每行有“详情”按钮，弹出独立面板展示完整字段与格式化后的 metadata JSON。
 4. 导出：导出当前页面已加载结果，文件名形如 `tracking-events-2026-05-07.xls`。
@@ -137,3 +137,19 @@
 4. `npm run dev` / `npm run dev:rust` 完整栈默认由脚本计算 API 端口；加载 `.env.local` 给后端使用后，脚本必须重新固定 `RUST_SERVER_TARGET`，避免 `.env.local` 中的旧代理目标覆盖本次启动的实际 API 端口。
 5. `npm run dev:web` 只启动前端，不会自动拉起 Rust API；如果 `.env.local` / 当前环境已经显式声明 `GENARRATIVE_RUNTIME_SERVER_TARGET`、`RUST_SERVER_TARGET`、`GENARRATIVE_API_TARGET` 或 `GENARRATIVE_API_PORT`，脚本必须固定使用该目标。目标当下不可用时只打印警告，不自动切到另一个端口，避免前端进程长时间绑定到随后会停掉的临时 API。
 6. 如果 `3000` 仍然返回 `500`，先确认浏览器是不是还开着旧的前端进程。当前脚本如果因为端口占用漂移到 `3001` / `3002`，应直接关掉旧进程后重启，而不是继续用旧的 3000 页面判断登录入口状态。
+
+## 11. 2026-05-10 `npm run api-server` 环境加载与短信 provider 排查记录
+
+本地单独启动 `api-server` 时，环境变量合并顺序固定为：
+
+```text
+外层 shell > .env > .env.local > .env.secrets.local
+```
+
+这保证 `.env.local` 能覆盖 `.env.example` 派生出的默认值，`.env.secrets.local` 能继续覆盖本地私密密钥配置。`scripts/api-server-dev.mjs` 不得让 `.env` 后加载并覆盖 `.env.local`，否则 `SMS_AUTH_ENABLED` 或 `SMS_AUTH_PROVIDER` 可能被压回错误值。
+
+排查“点击获取验证码但手机收不到短信”时，除了确认 `availableLoginMethods` 包含 `phone`，还必须确认当前进程实际使用的 provider：
+
+1. `SMS_AUTH_PROVIDER="mock"` 只用于本地 UI / 账号链路联调，不会向手机发送真实短信；此时应使用 `SMS_AUTH_MOCK_VERIFY_CODE`，默认 `123456`。
+2. 真实短信链路必须使用 `SMS_AUTH_PROVIDER="aliyun"`，并在修改 `.env.local` 后重启 `api-server`，运行中的进程不会自动切换 provider。
+3. 真实 provider 是否被使用，以 `api-server` 日志中的 `provider=aliyun`、`provider_request_id` 和 `provider_out_id` 为准。
@@ -21,6 +21,8 @@
 9. 后续关卡使用热身记录的边界进行安全提醒和暂停恢复。
 10. 热身结束后进入关卡选择。

+当前阶段先落浏览器本地 Demo。浏览器摄像头视频流已接入舞台背景；热身动作阶段已接入本地 mocap 动作检测接口，通过 `useMocapInput` 连接 `http://127.0.0.1:8876/stream` 对应的 WebSocket 流，消费手势、左右手坐标和跳跃事件推进招手、左右手挥动与原地跳跃步骤。正式语音播报接口继续预留适配层，不阻塞前端热身流程、调试输入和页面表现骨架落地。
+
 ## 2. 非目标范围

 热身关当前不包含以下内容：
@@ -33,6 +35,7 @@
 6. 不做特定用户识别。
 7. 不跨会话保存左右空间边界、手臂挥动空间和跳跃空间。
 8. 不对手部细节进行识别，只对肢体进行区分。
+9. 本阶段不处理无硬件、拒绝摄像头、多人入镜、识别丢失等异常流程；这些问题记录为待决策事项，后续硬件与摄像头方案稳定后再重新设计。

 ## 3. 运行入口与流向

@@ -44,6 +47,8 @@

 用户完成热身关所有步骤后，进入关卡选择。

+当前后续游戏仍在设计中。热身结束后可先展示“开始游戏”按钮作为关卡选择占位，用户点击后进入下一关占位界面。
+
 ### 3.3 固定流程顺序

 热身关必须按照以下顺序执行：
@@ -166,6 +171,20 @@
 4. 动作类状态没有最长等待时间。
 5. 动作类状态等待 3 秒后可以播放对应引导动画。

+### 6.3 开发者调试输入
+
+本地 Demo 需要支持开发者调试模式，用于无摄像头和自动化验证场景。
+
+调试映射如下：
+
+1. `A` 键映射用户向左移动。
+2. `D` 键映射用户向右移动。
+3. 鼠标左键按下并拖动映射左手轨迹。
+4. 鼠标右键按下并拖动映射右手轨迹。
+5. 空格键映射原地跳跃。
+
+调试输入只作为本地 Demo 与测试辅助，不代表正式动作识别硬件口径。正式摄像头接入后，位置、手势和跳跃判断需要按摄像头硬件调教结果重新校准。
+
 ## 7. 分步骤开发规格

 ### 7.1 进入热身关
@@ -438,6 +457,12 @@
 4. 右手挥动空间。
 5. 跳跃空间。

+当前 Demo 体验会话数据需要满足：
+
+1. 用户刷新产品或退出产品后失效。
+2. 用户只关闭当前游戏关卡并重新进入时，可以直接来到开始游戏界面，不强制重复热身。
+3. 首版可使用前端运行时内存或同等生命周期容器保存；不得跨产品刷新持久化保存。
+
 ### 8.2 当前 Demo 体验会话定义

 “当前 Demo 体验会话”指用户本次打开并体验 Demo 的过程。
@@ -523,10 +548,14 @@
 18. 关卡暂停时屏幕中央地面绿色圆圈。
 19. 关卡暂停提示文案。

+角色剪影、绿色圆环、虚影提醒、圆圈消失特效、手势引导动画和热身结束特效的正式视觉资源将通过 gpt-image-2 设计和生成。本地 Demo 阶段可以先使用 CSS、Canvas 或临时占位资源实现相同交互位置与状态，不把占位资源写死为正式资产。
+
 ## 12. 固定文案与语音清单

 以下文案需要作为屏幕中上方浮现文字，并同步语音播报。

+正式语音播报后续接入语音播报功能接口。本地 Demo 阶段保留播报适配层与调用点，可先只展示文字，不强制生成或播放正式语音资产。
+
 ```text
 欢迎你，小朋友，见到你真开心
 请你来到圆圈这里和我打个招呼吧
@@ -593,10 +622,58 @@

 当前需求已明确本文所需的热身关开发规格。

-以下内容未在当前文档中强行定义，后续如进入工程实现阶段，可再补充对应技术细节：
+以下内容作为待决策事项保留，后续硬件、摄像头和正式关卡设计稳定后再补充：

-1. 具体接入的动作识别 SDK 或硬件接口。
-2. 角色剪影、圆环、虚影提醒、特效、手势引导动画的具体资源文件命名。
-3. 当前 Demo 体验会话数据在前端状态、运行时上下文或其他容器中的具体存放位置。
-4. 绿色圆环、角色剪影、安全边界在线性空间或屏幕坐标中的具体计算公式。
-5. 关卡选择页的具体页面结构。
+1. 具体接入的动作识别 SDK、硬件接口和摄像头接口。
+2. 无硬件、摄像头拒绝授权、多人入镜、识别不到用户、跟踪丢失等异常流程。
+3. 角色剪影、圆环、虚影提醒、特效、手势引导动画的正式资源文件命名。
+4. 绿色圆环、角色剪影、安全边界在线性空间或屏幕坐标中的正式计算公式。
+5. 正式关卡选择页与后续游戏关卡的具体页面结构。
+
+## 15. 第 3 项本地 Demo 落地记录
+
+本地浏览器 Demo 入口已落在：
+
+```text
+/child-motion-demo
+```
+
+当前实现范围：
+
+1. `src/ChildMotionDemoApp.tsx` 挂载独立 Demo 应用壳。
+2. `src/components/child-motion-demo/childMotionWarmupModel.ts` 维护热身步骤、圆环目标、2 秒保持判定、热身校准记录和当前运行时会话完成标记。
+3. `src/components/child-motion-demo/ChildMotionWarmupDemo.tsx` 实现横屏舞台、背景虚化占位层、角色剪影、绿色圆环、手势引导、热身记录面板、热身完成后的“开始游戏”按钮和下一关占位界面。
+4. `src/services/child-motion-demo/childMotionDebugInput.ts` 保留开发者调试输入适配层，后续可被正式动作识别 SDK 适配层替换或并行接入。
+5. `src/routing/appRoutes.tsx` 新增 `/child-motion-demo` 独立路由，并复用 `VITE_ENABLE_EDUTAINMENT_ENTRY` 开关；开关关闭时不允许通过该直达路径进入 Demo。
+
+当前调试输入：
+
+1. `A` 键映射用户向左移动，松开后回到中心。
+2. `D` 键映射用户向右移动，松开后回到中心。
+3. 鼠标左键按下并拖动映射左手轨迹。
+4. 鼠标右键按下并拖动映射右手轨迹。
+5. 空格键映射原地跳跃。
+
+当前硬件和动作检测接口接入：
+
+1. 浏览器摄像头视频流已接入舞台背景。
+2. 热身关手势阶段已通过 `src/services/useMocapInput.ts` 接入本地 mocap WebSocket `/stream`。
+3. mocap 包支持从 `actions/action/gesture/gestures/event/name/type` 读取动作名，并支持 `hands[]`、`leftHand/rightHand`、`left_hand/right_hand` 读取左右手坐标。
+4. `wave_greeting` 可由 `wave/wave_greeting/hand_wave/open_palm` 等动作或 open palm 手势完成。
+5. `wave_left_hand` 和 `wave_right_hand` 优先消费对应左右手动作名；当硬件只持续输出手部坐标时，也可以根据连续手部横向轨迹完成挥手检测。
+6. `jump_once` 消费 `jump/jump_once/hop` 等跳跃动作事件完成。
+7. 键盘 `A/D/Space` 与鼠标左右键拖拽仍保留为本地 Demo 调试兜底，不代表正式硬件口径。
+
+当前未接入但已保留边界：
+
+1. 正式语音播报接口暂不接入，当前先展示热身文案。
+2. 正式 gpt-image-2 视觉资源暂不接入，当前使用 CSS 占位表达相同位置和状态。
+3. 后续关卡安全边界暂停逻辑暂未落地，当前只完成热身记录和下一关按钮占位。
+
+已执行的定向验证命令：
+
+```bash
+npx eslint src/components/child-motion-demo/ChildMotionWarmupDemo.tsx src/components/child-motion-demo/childMotionWarmupModel.ts src/components/child-motion-demo/ChildMotionWarmupDemo.test.tsx src/components/child-motion-demo/childMotionWarmupModel.test.ts src/services/child-motion-demo/childMotionDebugInput.ts src/services/child-motion-demo/childMotionDebugInput.test.ts src/services/child-motion-demo/index.ts src/ChildMotionDemoApp.tsx src/routing/appRoutes.tsx src/routing/appRoutes.test.ts --ext .ts,.tsx --max-warnings 0
+npx vitest run src/components/child-motion-demo/childMotionWarmupModel.test.ts src/components/child-motion-demo/ChildMotionWarmupDemo.test.tsx src/services/child-motion-demo/childMotionDebugInput.test.ts src/routing/appRoutes.test.ts
+npm run check:encoding
+```
@@ -46,7 +46,7 @@

 用户成功登录时，认证链路会通过统一后端埋点 helper 幂等记录当日 `daily_login` 并刷新任务进度；用户打开任务中心只记录 `task_center_view` 浏览事件，不再承担每日登录事实写入。用户点击领取时，后端校验当日进度、领奖记录和配置状态，然后同事务写入领奖记录与钱包流水。

-后台任务配置页的 `Event Key` 使用可搜索下拉控件，选项来自前端后台的埋点定义注册表。当前注册表默认包含 `daily_login`，展示中文名称和备注；后续新增任务依赖的埋点时，应先补充注册表，再开放运营配置。
+后台任务配置页的 `Event Key` 使用可搜索下拉控件，选项来自前端后台的埋点定义注册表。后台全量埋点筛选候选应对齐 `BACKEND_TRACKING_EVENT_COVERAGE_2026-05-09.md` 的事件清单；任务配置页只展示标记为个人任务可用的事件，当前仅开放 `daily_login`，展示中文名称和备注。后续新增任务依赖的埋点时，应先补充注册表并显式标记任务可用，再开放运营配置。

 ## 6. 接口

@@ -23,6 +23,9 @@
 7. 当前作品没有下一关时，通关弹窗展示后端 handoff 返回的相似作品；用户点击具体候选作品时直接 `startPuzzleRun(profileId, null)`，从目标作品第 `1` 关重新开始。
 8. 失败状态点击“重新开始”时，正式 run 使用当前关 `levelId` 重新 `startPuzzleRun`，草稿/本地 run 使用本地重建，二者都保留当前失败关卡。
 9. 结果页草稿试玩没有正式后端 run 时，继续使用本地 run、local leaderboard 和本地下一关兜底。
+10. 运行态输入采用全项目通用的 `src/services/input-devices/` 抽象层承接，指针、触控、mocap 等设备都先归一为 `press / move / release / tap / drop` 拖拽语义，再由拼图运行态解析具体拼块和落点。
+11. mocap `grab` 不是点击选中语义，而是持续拖拽语义；松手时按当前棋盘归一坐标提交 drop。合并大块只需要提交其中任一成员拼块 `pieceId`，本地拼图运行时会按 `mergedGroupId` 解析整组平移。
+12. 拼图作品详情或开局遇到后端 `404 / NOT_FOUND / 资源不存在` 时，平台入口不再停留在空详情或运行态错误页，而是清理当前拼图详情/run 状态并返回首页。

 ## 工程落点

@@ -38,6 +41,15 @@
 3. `src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`
   - 公开拼图玩法交互测试断言前端本地交换函数被调用。
   - 同时断言后端 `swap / drag` 不参与棋盘交互，后端 `leaderboard / next-level` 继续参与非即时链路。
+4. `src/services/input-devices/`
+   - `runtimeDragInputController` 提供设备无关的拖拽会话状态机。
+   - `runtimeInputGeometry` 提供屏幕坐标、归一坐标和网格命中的通用转换能力。
+   - 玩法组件只传入“这个点对应哪个目标”和“drop 到哪个目标”的玩法解释，不在输入层写拼图专用规则。
+5. `src/components/puzzle-runtime/PuzzleRuntimeShell.tsx`
+   - 鼠标/触控与 mocap 共用同一个 runtime drag controller。
+   - 合并块成员不再被 mocap 路径过滤；mocap 可从合并块任一占用格抓取，并复用本地运行时的大块拖拽规则。
+6. `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
+   - `openPuzzleDetail`、`openPuzzlePublicWorkDetail`、`startPuzzleRunFromProfile` 对拼图作品缺失统一回首页。

 ## 边界

@@ -5,6 +5,7 @@
 ## 文档列表

 - [CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md](./CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md)：冻结儿童动作识别互动玩法 Demo 固定热身关的开发落地规格，覆盖横屏展示、摄像头背景虚化、角色剪影、绿色圆环 2 秒保持、动作教学、当前会话内空间边界记录和后续关卡安全暂停规则。
+- [RUNTIME_INPUT_DEVICE_ABSTRACTION_2026-05-10.md](./RUNTIME_INPUT_DEVICE_ABSTRACTION_2026-05-10.md)：记录运行态输入设备抽象层，明确鼠标、触控、mocap 等设备统一归一为通用拖拽语义，玩法组件只负责解释目标和落点。
 - [RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md](./RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md)：记录 `server-rs` Cargo 依赖集中配置口径，第三方版本和 workspace 内部 crate path 统一维护在根 `server-rs/Cargo.toml`，成员 crate 只保留 feature/optional 差异。
 - [DEV_RUST_STACK_PORT_CONFLICT_PRECHECK_2026-05-09.md](./DEV_RUST_STACK_PORT_CONFLICT_PRECHECK_2026-05-09.md)：记录本地完整 Rust 栈启动时 `api-server`、主站 Vite 和后台 Vite 端口占用的误判根因、脚本预检策略和 Windows 排障命令。
 - [VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md](./VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md)：记录 GPT-image-2 图片生成从 APIMart 迁移到 VectorEngine `gpt-image-2-all` 的接口、环境变量、尺寸映射、错误口径和验收命令。
@@ -0,0 +1,57 @@
+# 运行态输入设备抽象层 2026-05-10
+
+## 背景
+
+拼图运行态接入 mocap 后，鼠标/触控和 mocap 曾各自维护一套选择、坐标换算和拖拽提交逻辑。这样会让新设备只能在单个玩法里打补丁，也容易出现同一动作在不同设备下语义不一致的问题：例如 mocap `grab` 只触发选中，而不是像鼠标按住一样持续拖拽。
+
+后续运行态还会接摇杆、键盘、体感、摄像头手势等输入来源，因此输入设备接入必须收口到全项目通用层。
+
+## 决策
+
+新增 `src/services/input-devices/` 作为前端运行态通用输入设备抽象层：
+
+1. `runtimeDragInputController` 只维护设备无关的拖拽会话状态机。
+2. `runtimeInputGeometry` 只处理 client 坐标、归一坐标、元素边界和网格命中换算。
+3. 设备适配层把鼠标、触控、mocap 等输入归一为 `press / move / release / tap / drop`。
+4. 玩法组件负责把通用输入点解释成自己的目标对象和落点，不把拼图、方洞或大鱼等玩法规则写进输入层。
+
+## 当前接入
+
+`useMocapInput` 解析 mocap `hands[].landmarks` 时应优先用 MediaPipe 21 点里的 `wrist / index_mcp / middle_mcp / ring_mcp / pinky_mcp` 加权计算掌心派生点；少于 3 个掌心关键点时才回退到 `wrist` 或直出 `hand.x/y`。这样运行态光标不会直接贴在腕部或指尖。
+
+拼图运行态已接入该层：
+
+- 鼠标/触控 `pointerdown / pointermove / pointerup` 进入同一个 drag controller。
+- mocap `grab` 进入同一个 drag controller，并强制使用持续拖拽语义。
+- mocap 光标按 60Hz 插值更新 UI 位置，并在拖拽中用插值后的当前点持续驱动输入层，避免输入包帧率低或抖动时出现明显跳变。
+- 合并大块由拼图运行态把手部坐标命中到任一成员拼块；本地拼图运行时再按 `mergedGroupId` 执行整组平移。
+
+## 接入规则
+
+新玩法或新设备接入时遵循以下边界：
+
+1. 输入层可以知道设备类型和几何换算，但不能知道玩法业务规则。
+2. 设备适配层只负责把原始输入转换成通用输入事件。
+3. 玩法壳层负责从通用输入点解析本玩法目标，例如拼块、洞口、角色或实体。
+4. 玩法壳层负责决定 drop 后调用哪个本地运行态函数或后端接口。
+5. 需要取消输入时优先按 `inputId` 取消，避免 mocap 丢帧误伤正在进行的鼠标/触控会话。
+
+## 验证
+
+基础抽象层验证：
+
+```bash
+npm run test -- src\services\input-devices\runtimeDragInputController.test.ts src\services\useMocapInput.test.ts
+```
+
+拼图接入验证：
+
+```bash
+npm run test -- src\components\puzzle-runtime\PuzzleRuntimeShell.test.tsx
+```
+
+跨平台入口缺失作品兜底验证：
+
+```bash
+npm run test -- src\components\rpg-entry\RpgEntryFlowShell.agent.interaction.test.tsx -t "missing puzzle public detail returns to platform home"
+```
@@ -25,24 +25,33 @@ npm run dev:rust

 默认端口：

-1. Web 前端：`http://127.0.0.1:3000`
-2. Rust `api-server`：`http://127.0.0.1:8082`
-3. SpacetimeDB standalone：`http://127.0.0.1:3101`
-4. SpacetimeDB database：优先读取仓库根目录 `spacetime.local.json` 的 `database` 字段；没有该字段时才回退到 `genarrative-dev`
-5. SpacetimeDB 本地数据与日志目录：`server-rs/.spacetimedb/local`
+1. Web 前端：优先 `http://127.0.0.1:3000`
+2. Rust `api-server`：优先 `http://127.0.0.1:8082`
+3. SpacetimeDB standalone：优先 `http://127.0.0.1:3101`
+4. 后台 Web 前端：优先 `http://127.0.0.1:3102`
+5. SpacetimeDB database：优先读取仓库根目录 `spacetime.local.json` 的 `database` 字段；没有该字段时才回退到 `genarrative-dev`
+6. SpacetimeDB 本地数据与日志目录：`server-rs/.spacetimedb/local`
+
+启动前端口处理：
+
+1. `npm run dev` / `npm run dev:rust` 会先检查 SpacetimeDB、Rust `api-server`、主站 Vite、后台 Vite 需要使用的端口。
+2. 如果优先端口不可用，脚本会从该端口开始向后寻找可用端口，并将解析后的端口覆盖到后续 `spacetime start`、`spacetime publish --server`、`GENARRATIVE_API_PORT`、`RUST_SERVER_TARGET`、`GENARRATIVE_RUNTIME_SERVER_TARGET`、`ADMIN_API_TARGET` 与 Vite 启动参数。
+3. 控制台会打印 `[dev:ports] ... 可用` 或 `[dev:ports] ... 不可用，改用 ...`，排查代理错配时以该日志和后续 `[dev:rust] web/admin web/rust api/spacetime` 实际地址为准。
+4. 单独 `npm run dev:web` 也会检查主站 Vite 端口；`WEB_PORT` 或默认 `3000` 不可用时，会自动切到后续可用端口并继续严格端口启动。

 默认流程：

 1. 检查 `cargo`、`node` 与 `spacetime` CLI。
-2. Windows Git Bash 下如 `server-rs/.spacetimedb/local/bin/current/spacetimedb-cli.exe` 不存在，先把本机 `spacetime` 所在安装目录的 `bin/` 与 `spacetime.exe` 同步到 `server-rs/.spacetimedb/local/`。
-3. 启动 SpacetimeDB 前先检查 `server-rs/.spacetimedb/local/data/spacetime.pid`：如果 pid 对应进程仍存在，且同目录 `dev-rust-spacetime-url` 中记录的 URL 可被 `spacetime server ping` 判定在线，则直接复用该宿主；如果 URL 记录缺失，会依次尝试从 `logs/dev-rust-spacetime-start.log` 和 `logs/spacetime-standalone.log` 中解析最近一次监听地址兜底。否则按正常流程重新启动。
-4. 如果确认需要新启动 SpacetimeDB，脚本会先检测 `127.0.0.1:3101` 是否可监听；若已占用，输出占用进程并选择从 `3101` 起向后的最近可用端口，再执行 `spacetime start --data-dir server-rs/.spacetimedb/local/data --listen-addr <实际地址>`。启动成功后把实际 URL 写入 `server-rs/.spacetimedb/local/data/dev-rust-spacetime-url`，后续 publish 与 `api-server` 都使用同一个实际 URL。
-5. 等待 SpacetimeDB 就绪：优先接受 `spacetime server ping http://127.0.0.1:<spacetime-port>` 输出中的 `Server is online:`；如果 Windows 下 SpacetimeDB CLI `2.1.0` 对已经监听的 standalone 仍打印 `502 Bad Gateway`，脚本会兜底请求 `http://127.0.0.1:<spacetime-port>/v1/ping`，只有该健康端点返回 `2xx` 时才放行。不能只依赖 CLI 退出码，因为 CLI 在 `502 Bad Gateway` 时也可能返回退出码 `0`。
-6. 执行 `spacetime publish <本地数据库名> --server <实际 SpacetimeDB URL> --module-path server-rs/crates/spacetime-module --build-options="--debug" -c=on-conflict --yes`，确保 publish 仍由 SpacetimeDB CLI 负责构建和发布模块，同时使用 debug 构建参数降低本地开发等待时间；当前开发阶段允许新版模块表结构变化且发生 schema 冲突时清除旧模块数据。
-7. 启动 `api-server` 前先检测默认 API 端口 `8082` 是否可监听；若已占用，输出占用进程并选择从 `8082` 起向后的最近可用端口。随后注入 `GENARRATIVE_API_*` 与 `GENARRATIVE_SPACETIME_*`，启动默认 debug profile 的 `cargo run -p api-server`；直接运行 `api-server` 时，如未显式设置 `GENARRATIVE_SPACETIME_DATABASE`，服务端也会向上查找 `spacetime.local.json` 作为本地默认库名。
-8. 等待 `http://127.0.0.1:<api-port>/healthz` 返回 HTTP 响应后再启动 Vite，避免前端初始化请求早于 Rust `api-server` 监听完成并在终端刷出 `ECONNREFUSED 127.0.0.1:<api-port>`。
-9. 注入 `RUST_SERVER_TARGET`、`GENARRATIVE_RUNTIME_SERVER_TARGET` 后启动 Vite。
-10. 任一子进程退出时，脚本回收其余子进程。
+2. 检查并解析本次联调需要使用的端口；端口不可用时先寻找可用端口，再把实际端口传给后续流程。
+3. Windows Git Bash 下如 `server-rs/.spacetimedb/local/bin/current/spacetimedb-cli.exe` 不存在，先把本机 `spacetime` 所在安装目录的 `bin/` 与 `spacetime.exe` 同步到 `server-rs/.spacetimedb/local/`。
+4. 启动 SpacetimeDB 前先检查 `server-rs/.spacetimedb/local/data/spacetime.pid`：如果 pid 对应进程仍存在，且同目录 `dev-rust-spacetime-url` 中记录的 URL 可被 `spacetime server ping` 判定在线，则直接复用该宿主；如果 URL 记录缺失，会依次尝试从 `logs/dev-rust-spacetime-start.log` 和 `logs/spacetime-standalone.log` 中解析最近一次监听地址兜底。否则按正常流程重新启动。
+5. 如果确认需要新启动 SpacetimeDB，脚本会先检测 `127.0.0.1:3101` 是否可监听；若已占用，输出占用进程并选择从 `3101` 起向后的最近可用端口，再执行 `spacetime start --data-dir server-rs/.spacetimedb/local/data --listen-addr <实际地址>`。启动成功后把实际 URL 写入 `server-rs/.spacetimedb/local/data/dev-rust-spacetime-url`，后续 publish 与 `api-server` 都使用同一个实际 URL。
+6. 等待 SpacetimeDB 就绪：优先接受 `spacetime server ping http://127.0.0.1:<spacetime-port>` 输出中的 `Server is online:`；如果 Windows 下 SpacetimeDB CLI `2.1.0` 对已经监听的 standalone 仍打印 `502 Bad Gateway`，脚本会兜底请求 `http://127.0.0.1:<spacetime-port>/v1/ping`，只有该健康端点返回 `2xx` 时才放行。不能只依赖 CLI 退出码，因为 CLI 在 `502 Bad Gateway` 时也可能返回退出码 `0`。
+7. 执行 `spacetime publish <本地数据库名> --server <实际 SpacetimeDB URL> --module-path server-rs/crates/spacetime-module --build-options="--debug" -c=on-conflict --yes`，确保 publish 仍由 SpacetimeDB CLI 负责构建和发布模块，同时使用 debug 构建参数降低本地开发等待时间；当前开发阶段允许新版模块表结构变化且发生 schema 冲突时清除旧模块数据。
+8. 启动 `api-server` 前先检测默认 API 端口 `8082` 是否可监听；若已占用，输出占用进程并选择从 `8082` 起向后的最近可用端口。随后注入 `GENARRATIVE_API_*` 与 `GENARRATIVE_SPACETIME_*`，启动默认 debug profile 的 `cargo run -p api-server`；直接运行 `api-server` 时，如未显式设置 `GENARRATIVE_SPACETIME_DATABASE`，服务端也会向上查找 `spacetime.local.json` 作为本地默认库名。
+9. 等待 `http://127.0.0.1:<api-port>/healthz` 返回 HTTP 响应后再启动 Vite，避免前端初始化请求早于 Rust `api-server` 监听完成并在终端刷出 `ECONNREFUSED 127.0.0.1:<api-port>`。
+10. 注入 `RUST_SERVER_TARGET`、`GENARRATIVE_RUNTIME_SERVER_TARGET` 后启动 Vite。
+11. 任一子进程退出时，脚本回收其余子进程。

 Vite 代理覆盖范围：

@@ -45,6 +45,8 @@ export function loadApiServerEnv(
  target,
  protectedKeys = shellEnvKeys,
 ) {
+  // 保持与 dev-web-rust.mjs / dev-rust-stack.sh 一致：
+  // shell > .env > .env.local > .env.secrets.local。
  for (const fileName of LOCAL_ENV_FILES) {
    loadEnvFile(resolve(repoRootPath, fileName), target, protectedKeys);
  }
@@ -17,7 +17,7 @@ usage() {

 说明:
  1. 默认同时启动 SpacetimeDB standalone、Rust api-server、主站 Vite 与后台 Vite。
-  2. 当前开发阶段默认 publish server-rs/crates/spacetime-module 时追加 -c=on-conflict 在结构冲突时清理旧模块数据。
+  2. 当前开发阶段默认 publish server-rs/crates/spacetime-module 时追加 -c=on-conflict，在结构冲突时清理旧模块数据。
  3. 只有显式传入 --preserve-database 时，才会跳过 -c=on-conflict。
  4. SpacetimeDB 默认使用 server-rs/.spacetimedb/local/data 作为本地数据目录；需要新启动时会先检测端口并选择最近可用端口。
  5. 默认在发布模块前随机生成迁移引导密钥，注入 GENARRATIVE_SPACETIME_MIGRATION_BOOTSTRAP_SECRET 并显示在控制台。
@@ -99,6 +99,25 @@ NODE
  )
 }

+resolve_dev_stack_ports() {
+  local key
+  local value
+
+  while IFS='=' read -r key value; do
+    case "${key}" in
+      SPACETIME_PORT|API_PORT|WEB_PORT|ADMIN_WEB_PORT)
+        export "${key}=${value}"
+        ;;
+    esac
+  done < <(
+    node "${REPO_ROOT}/scripts/dev-stack-port-utils.mjs" resolve-dev-stack \
+      "spacetime:${SPACETIME_HOST}:${SPACETIME_PORT}" \
+      "api:${API_TARGET_HOST}:${API_PORT}" \
+      "web:${WEB_HOST}:${WEB_PORT}" \
+      "adminWeb:${ADMIN_WEB_TARGET_HOST}:${ADMIN_WEB_PORT}"
+  )
+}
+
 cleanup() {
  local index

@@ -876,8 +895,10 @@ fi

 SPACETIME_SERVER="http://${SPACETIME_HOST}:${SPACETIME_PORT}"
 API_TARGET_HOST="$(resolve_client_host "${API_HOST}")"
-RUST_SERVER_TARGET="http://${API_TARGET_HOST}:${API_PORT}"
 ADMIN_WEB_TARGET_HOST="$(resolve_client_host "${ADMIN_WEB_HOST}")"
+resolve_dev_stack_ports
+SPACETIME_SERVER="http://${SPACETIME_HOST}:${SPACETIME_PORT}"
+RUST_SERVER_TARGET="http://${API_TARGET_HOST}:${API_PORT}"

 trap cleanup EXIT INT TERM

@@ -906,24 +927,22 @@ if [[ "${SKIP_SPACETIME}" -ne 1 ]]; then
      exit 1
    fi

-    SPACETIME_PORT="$(find_nearest_available_port "${SPACETIME_HOST}" "${SPACETIME_PORT}" "SpacetimeDB")"
-    SPACETIME_SERVER="http://${SPACETIME_HOST}:${SPACETIME_PORT}"
-
-    SPACETIME_START_LOG="$(spacetime_start_log_path "${SPACETIME_DATA_DIR}")"
-    mkdir -p "$(dirname -- "${SPACETIME_START_LOG}")"
-    : >"${SPACETIME_START_LOG}"
-    echo "[dev:rust] 启动 spacetimedb"
-    (
-      cd "${SERVER_RS_DIR}"
-      # 启动前已经由脚本选定端口，避免 api-server 和 SpacetimeDB 对数据库地址认知不一致。
-      spacetime \
-        start \
-        --data-dir "${SPACETIME_DATA_DIR}" \
-        --listen-addr "${SPACETIME_HOST}:${SPACETIME_PORT}" \
-        --non-interactive
-    ) 2>&1 | tee "${SPACETIME_START_LOG}" &
-    PIDS+=("$!")
-    NAMES+=("spacetimedb")
+  SPACETIME_START_LOG="${SPACETIME_DATA_DIR}/logs/dev-rust-spacetime-start.log"
+  mkdir -p "$(dirname -- "${SPACETIME_START_LOG}")"
+  : >"${SPACETIME_START_LOG}"
+  echo "[dev:rust] 启动 spacetimedb"
+  (
+    cd "${SERVER_RS_DIR}"
+    # 当目标端口被占用时，SpacetimeDB 会询问是否使用最近的可用端口；
+    # 这里直接发送回车接受默认建议，再从启动日志解析实际监听端口。
+    printf '\n' | spacetime \
+      start \
+      --data-dir "${SPACETIME_DATA_DIR}" \
+      --listen-addr "${SPACETIME_HOST}:${SPACETIME_PORT}" \
+      --non-interactive
+  ) 2>&1 | tee "${SPACETIME_START_LOG}" &
+  PIDS+=("$!")
+  NAMES+=("spacetimedb")

    SPACETIME_LISTEN_ADDR="$(wait_for_spacetime_listen_addr "${SPACETIME_START_LOG}" "${SPACETIME_TIMEOUT_SECONDS}" "${PIDS[0]:-}")"
    SPACETIME_PORT="$(port_from_listen_addr "${SPACETIME_LISTEN_ADDR}")"
@@ -0,0 +1,164 @@
+import {createServer} from 'node:net';
+
+function toListenHosts(host) {
+  if (host === '0.0.0.0') {
+    return ['0.0.0.0'];
+  }
+
+  if (host === '::') {
+    return ['::'];
+  }
+
+  return [host];
+}
+
+export function normalizePort(value, fallback) {
+  const port = Number.parseInt(String(value ?? ''), 10);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    return fallback;
+  }
+
+  return port;
+}
+
+export async function isPortAvailable({host, port}) {
+  if (port === 0) {
+    return true;
+  }
+
+  const listenHosts = toListenHosts(host);
+
+  for (const listenHost of listenHosts) {
+    const available = await new Promise((resolve) => {
+      const server = createServer();
+      server.unref();
+      server.once('error', () => resolve(false));
+      server.listen({host: listenHost, port}, () => {
+        server.close(() => resolve(true));
+      });
+    });
+
+    if (!available) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+export async function findAvailablePort({host, preferredPort, reservedPorts = new Set(), maxAttempts = 200}) {
+  const startPort = normalizePort(preferredPort, 0);
+
+  if (startPort === 0) {
+    return await reserveEphemeralPort(host, reservedPorts);
+  }
+
+  for (let offset = 0; offset <= maxAttempts; offset += 1) {
+    const candidate = startPort + offset;
+    if (candidate > 65535) {
+      break;
+    }
+
+    if (reservedPorts.has(candidate)) {
+      continue;
+    }
+
+    if (await isPortAvailable({host, port: candidate})) {
+      return candidate;
+    }
+  }
+
+  throw new Error(`无法从 ${host}:${startPort} 开始找到可用端口`);
+}
+
+async function reserveEphemeralPort(host, reservedPorts) {
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    const port = await new Promise((resolve, reject) => {
+      const server = createServer();
+      server.unref();
+      server.once('error', reject);
+      server.listen({host, port: 0}, () => {
+        const address = server.address();
+        const resolvedPort = typeof address === 'object' && address ? address.port : 0;
+        server.close(() => resolve(resolvedPort));
+      });
+    });
+
+    if (typeof port === 'number' && port > 0 && !reservedPorts.has(port)) {
+      return port;
+    }
+  }
+
+  throw new Error(`无法为 ${host} 分配临时可用端口`);
+}
+
+export async function resolveDevStackPorts(config) {
+  const reservedPorts = new Set();
+  const entries = [
+    ['spacetime', config.spacetime],
+    ['api', config.api],
+    ['web', config.web],
+    ['adminWeb', config.adminWeb],
+  ].filter(([, portConfig]) => Boolean(portConfig));
+  const result = {};
+
+  for (const [name, portConfig] of entries) {
+    const resolvedPort = await findAvailablePort({
+      host: portConfig.host,
+      preferredPort: portConfig.preferredPort,
+      reservedPorts,
+    });
+    reservedPorts.add(resolvedPort);
+    result[name] = resolvedPort;
+  }
+
+  return result;
+}
+
+export function formatPortDecision({name, host, preferredPort, resolvedPort}) {
+  if (preferredPort === resolvedPort && preferredPort !== 0) {
+    return `[dev:ports] ${name}: ${host}:${resolvedPort} 可用`;
+  }
+
+  return `[dev:ports] ${name}: ${host}:${preferredPort} 不可用，改用 ${host}:${resolvedPort}`;
+}
+
+function parseCliPortConfig(rawArgs) {
+  const config = {};
+
+  for (const rawArg of rawArgs) {
+    const [name, host, rawPreferredPort] = rawArg.split(':');
+    if (!name || !host || rawPreferredPort == null) {
+      throw new Error(`端口配置参数格式错误: ${rawArg}`);
+    }
+
+    config[name] = {
+      host,
+      preferredPort: normalizePort(rawPreferredPort, 0),
+    };
+  }
+
+  return config;
+}
+
+function envKeyForPortName(name) {
+  return `${name.replace(/[A-Z]/gu, (letter) => `_${letter}`).toUpperCase()}_PORT`;
+}
+
+if (process.argv[2] === 'resolve-dev-stack') {
+  const config = parseCliPortConfig(process.argv.slice(3));
+  const resolvedPorts = await resolveDevStackPorts(config);
+
+  for (const [name, resolvedPort] of Object.entries(resolvedPorts)) {
+    const portConfig = config[name];
+    console.error(
+      formatPortDecision({
+        name,
+        host: portConfig.host,
+        preferredPort: portConfig.preferredPort,
+        resolvedPort,
+      }),
+    );
+    console.log(`${envKeyForPortName(name)}=${resolvedPort}`);
+  }
+}
@@ -0,0 +1,51 @@
+import {createServer} from 'node:net';
+import {describe, expect, it} from 'vitest';
+import {
+  findAvailablePort,
+  resolveDevStackPorts,
+} from './dev-stack-port-utils.mjs';
+
+function reservePort(port) {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', () => {
+      server.off('error', reject);
+      resolve(server);
+    });
+  });
+}
+
+describe('dev stack port utils', () => {
+  it('使用端口可用性检查为被占用端口寻找后续可用端口', async () => {
+    const firstServer = await reservePort(0);
+    const firstPort = firstServer.address().port;
+    const secondServer = await reservePort(firstPort + 1);
+
+    try {
+      const availablePort = await findAvailablePort({
+        host: '127.0.0.1',
+        preferredPort: firstPort,
+      });
+
+      expect(availablePort).toBeGreaterThan(firstPort + 1);
+    } finally {
+      await Promise.all([
+        new Promise((resolve) => firstServer.close(resolve)),
+        new Promise((resolve) => secondServer.close(resolve)),
+      ]);
+    }
+  });
+
+  it('为 npm run dev 的所有后续流程解析互不冲突的端口', async () => {
+    const resolvedPorts = await resolveDevStackPorts({
+      spacetime: {host: '127.0.0.1', preferredPort: 0},
+      api: {host: '127.0.0.1', preferredPort: 0},
+      web: {host: '127.0.0.1', preferredPort: 0},
+      adminWeb: {host: '127.0.0.1', preferredPort: 0},
+    });
+
+    expect(new Set(Object.values(resolvedPorts)).size).toBe(4);
+  });
+});
@@ -1,6 +1,11 @@
 import {spawn} from 'node:child_process';
 import {existsSync, readFileSync} from 'node:fs';
 import {resolve} from 'node:path';
+import {
+  findAvailablePort,
+  formatPortDecision,
+  normalizePort,
+} from './dev-stack-port-utils.mjs';

 const repoRoot = process.cwd();
 const shellEnvKeys = new Set(Object.keys(process.env));
@@ -121,9 +126,24 @@ const mergedEnv = {

 console.log(`[dev:web] backend=rust target=${mergedEnv.GENARRATIVE_RUNTIME_SERVER_TARGET}`);

+const webHost = '0.0.0.0';
+const preferredWebPort = normalizePort(fileEnv.WEB_PORT, 3000);
+const webPort = await findAvailablePort({
+  host: webHost,
+  preferredPort: preferredWebPort,
+});
+console.log(
+  formatPortDecision({
+    name: 'web',
+    host: webHost,
+    preferredPort: preferredWebPort,
+    resolvedPort: webPort,
+  }),
+);
+
 const child = spawn(
  'node',
-  ['scripts/vite-cli.mjs', '--port=3000', '--host=0.0.0.0', '--strictPort'],
+  ['scripts/vite-cli.mjs', `--port=${webPort}`, `--host=${webHost}`, '--strictPort'],
  {
    cwd: process.cwd(),
    env: mergedEnv,
@@ -0,0 +1,5 @@
+import { ChildMotionWarmupDemo } from './components/child-motion-demo/ChildMotionWarmupDemo';
+
+export default function ChildMotionDemoApp() {
+  return <ChildMotionWarmupDemo />;
+}
@@ -0,0 +1,364 @@
+/* @vitest-environment jsdom */
+
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, beforeEach, expect, test, vi } from 'vitest';
+
+import { ChildMotionWarmupDemo } from './ChildMotionWarmupDemo';
+import {
+  markChildMotionWarmupCompletedInRuntime,
+  resetChildMotionWarmupRuntimeSession,
+} from './childMotionWarmupModel';
+
+const mocapMock = vi.hoisted(() => ({
+  status: 'connected' as 'idle' | 'connecting' | 'connected' | 'error',
+  command: null as null | {
+    actions: string[];
+    hands?: Array<{ x: number; y: number; state: string; side: string }>;
+    primaryHand?: { x: number; y: number; state: string; side: string } | null;
+    leftHand?: { x: number; y: number; state: string; side: string } | null;
+    rightHand?: { x: number; y: number; state: string; side: string } | null;
+    bodyCenter?: { x: number; y: number } | null;
+  },
+  receivedAtMs: 1,
+}));
+
+vi.mock('../../services/useMocapInput', () => ({
+  useMocapInput: ({ enabled }: { enabled: boolean }) => ({
+    status: enabled ? mocapMock.status : 'idle',
+    latestCommand: enabled ? mocapMock.command : null,
+    rawPacketPreview:
+      enabled && mocapMock.command
+        ? {
+            text: JSON.stringify(mocapMock.command),
+            receivedAtMs: mocapMock.receivedAtMs,
+          }
+        : null,
+    error: null,
+  }),
+}));
+
+beforeEach(() => {
+  resetChildMotionWarmupRuntimeSession();
+  vi.restoreAllMocks();
+  mocapMock.status = 'connected';
+  mocapMock.command = null;
+  mocapMock.receivedAtMs = 1;
+  Object.defineProperty(navigator, 'mediaDevices', {
+    configurable: true,
+    value: undefined,
+  });
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+test('renders the warmup stage and starts with the center ring step', () => {
+  render(<ChildMotionWarmupDemo />);
+
+  expect(screen.getByTestId('child-motion-demo')).toBeTruthy();
+  expect(screen.getByText('来到圆圈这里')).toBeTruthy();
+  expect(screen.getByLabelText('绿色圆环')).toBeTruthy();
+  expect(screen.getByText('请横屏体验')).toBeTruthy();
+});
+
+test('re-entering within the same runtime session opens the start button', () => {
+  markChildMotionWarmupCompletedInRuntime();
+
+  render(<ChildMotionWarmupDemo />);
+
+  expect(screen.getByRole('button', { name: '开始游戏' })).toBeTruthy();
+});
+
+test('developer keyboard input moves the avatar and triggers jump state', () => {
+  render(<ChildMotionWarmupDemo />);
+
+  const avatar = screen.getByTestId('child-motion-avatar');
+
+  fireEvent.keyDown(window, { key: 'a', code: 'KeyA' });
+  expect(avatar.getAttribute('style')).toContain('left: 34%');
+
+  fireEvent.keyDown(window, { key: 'd', code: 'KeyD' });
+  expect(avatar.getAttribute('style')).toContain('left: 66%');
+
+  fireEvent.keyUp(window, { key: 'd', code: 'KeyD' });
+  expect(avatar.getAttribute('style')).toContain('left: 50%');
+
+  fireEvent.keyDown(window, { key: ' ', code: 'Space' });
+  expect(avatar.className).toContain('child-motion-avatar--jumping');
+});
+
+test('mocap body center keeps the warmup flow on the motion data source', async () => {
+  vi.useFakeTimers();
+  mocapMock.command = {
+    actions: [],
+    bodyCenter: { x: 0.5, y: 0.6 },
+    hands: [],
+    primaryHand: null,
+    leftHand: null,
+    rightHand: null,
+  };
+  const { rerender, unmount } = render(<ChildMotionWarmupDemo />);
+
+  expect(screen.queryByText('摄像头暂不可用，已切换到本地演示')).toBeNull();
+  expect(screen.queryByText('动作数据已连接，等待识别')).toBeNull();
+  expect(screen.getByTestId('child-motion-avatar').getAttribute('style')).toContain(
+    'left: 50%',
+  );
+
+  await act(async () => {
+    vi.advanceTimersByTime(2100);
+    await vi.runOnlyPendingTimersAsync();
+  });
+  await vi.waitFor(() => {
+    expect(screen.getByText('打个招呼')).toBeTruthy();
+  });
+
+  mocapMock.command = {
+    actions: ['open_palm'],
+    bodyCenter: { x: 0.5, y: 0.6 },
+    hands: [{ x: 0.48, y: 0.34, state: 'open_palm', side: 'left' }],
+    primaryHand: { x: 0.48, y: 0.34, state: 'open_palm', side: 'left' },
+    leftHand: { x: 0.48, y: 0.34, state: 'open_palm', side: 'left' },
+    rightHand: null,
+  };
+  mocapMock.receivedAtMs += 1;
+  await act(async () => {
+    rerender(<ChildMotionWarmupDemo />);
+    vi.advanceTimersByTime(1000);
+    await vi.runOnlyPendingTimersAsync();
+  });
+
+  await vi.waitFor(() => {
+    expect(screen.getByText('准备热身')).toBeTruthy();
+  });
+
+  await act(async () => {
+    vi.advanceTimersByTime(1000);
+    await vi.runOnlyPendingTimersAsync();
+  });
+
+  await vi.waitFor(() => {
+    expect(screen.getByRole('heading', { name: '向左一步' })).toBeTruthy();
+  });
+
+  mocapMock.command = {
+    actions: [],
+    bodyCenter: { x: 0.34, y: 0.6 },
+    hands: [],
+    primaryHand: null,
+    leftHand: null,
+    rightHand: null,
+  };
+  mocapMock.receivedAtMs += 1;
+  await act(async () => {
+    rerender(<ChildMotionWarmupDemo />);
+  });
+  await vi.waitFor(() => {
+    expect(screen.getByTestId('child-motion-avatar').getAttribute('style')).toContain(
+      'left: 34%',
+    );
+  });
+  await act(async () => {
+    vi.advanceTimersByTime(2100);
+    await vi.runOnlyPendingTimersAsync();
+  });
+
+  await vi.waitFor(() => {
+    expect(screen.getByRole('heading', { name: '回到中间来' })).toBeTruthy();
+  });
+
+  await act(async () => {
+    unmount();
+  });
+  vi.useRealTimers();
+});
+
+test('mocap open palm completes the greeting wave step', async () => {
+  vi.useFakeTimers();
+  const { rerender, unmount } = render(<ChildMotionWarmupDemo />);
+
+  await act(async () => {
+    vi.advanceTimersByTime(2100);
+    await vi.runOnlyPendingTimersAsync();
+  });
+  await vi.waitFor(() => {
+    expect(screen.getByText('打个招呼')).toBeTruthy();
+  });
+
+  mocapMock.command = {
+    actions: ['open_palm'],
+    hands: [{ x: 0.46, y: 0.34, state: 'open_palm', side: 'left' }],
+    primaryHand: { x: 0.46, y: 0.34, state: 'open_palm', side: 'left' },
+    leftHand: { x: 0.46, y: 0.34, state: 'open_palm', side: 'left' },
+    rightHand: null,
+  };
+  mocapMock.receivedAtMs += 1;
+  await act(async () => {
+    rerender(<ChildMotionWarmupDemo />);
+  });
+
+  await vi.waitFor(() => {
+    expect(screen.getByText('准备热身')).toBeTruthy();
+  });
+  await act(async () => {
+    unmount();
+  });
+  vi.useRealTimers();
+});
+
+test('mocap hand tracks complete left and right wave steps only after movement is visible', async () => {
+  vi.useFakeTimers();
+  const { rerender, unmount } = render(<ChildMotionWarmupDemo />);
+
+  const advancePositionStep = async (key: string, code: string) => {
+    await act(async () => {
+      fireEvent.keyDown(window, { key, code });
+    });
+    await act(async () => {
+      vi.advanceTimersByTime(2100);
+      await vi.runOnlyPendingTimersAsync();
+    });
+    await act(async () => {
+      fireEvent.keyUp(window, { key, code });
+    });
+  };
+
+  await act(async () => {
+    vi.advanceTimersByTime(2100);
+    await vi.runOnlyPendingTimersAsync();
+  });
+  await vi.waitFor(() => {
+    expect(screen.getByText('打个招呼')).toBeTruthy();
+  });
+
+  mocapMock.command = {
+    actions: ['open_palm'],
+    hands: [{ x: 0.48, y: 0.34, state: 'open_palm', side: 'left' }],
+    primaryHand: { x: 0.48, y: 0.34, state: 'open_palm', side: 'left' },
+    leftHand: { x: 0.48, y: 0.34, state: 'open_palm', side: 'left' },
+    rightHand: null,
+  };
+  mocapMock.receivedAtMs += 1;
+  await act(async () => {
+    rerender(<ChildMotionWarmupDemo />);
+  });
+
+  await act(async () => {
+    vi.advanceTimersByTime(1000);
+    await vi.runOnlyPendingTimersAsync();
+  });
+  await advancePositionStep('a', 'KeyA');
+  await act(async () => {
+    vi.advanceTimersByTime(120);
+    await vi.runOnlyPendingTimersAsync();
+    vi.advanceTimersByTime(2100);
+    await vi.runOnlyPendingTimersAsync();
+  });
+  await advancePositionStep('d', 'KeyD');
+  await act(async () => {
+    vi.advanceTimersByTime(120);
+    await vi.runOnlyPendingTimersAsync();
+    vi.advanceTimersByTime(2100);
+    await vi.runOnlyPendingTimersAsync();
+  });
+  await vi.waitFor(() => {
+    expect(screen.getByRole('heading', { name: '挥动左手' })).toBeTruthy();
+  });
+
+  mocapMock.command = {
+    actions: [],
+    leftHand: { x: 0.3, y: 0.38, state: 'unknown', side: 'left' },
+    primaryHand: { x: 0.3, y: 0.38, state: 'unknown', side: 'left' },
+    rightHand: null,
+  };
+  mocapMock.receivedAtMs += 1;
+  await act(async () => {
+    rerender(<ChildMotionWarmupDemo />);
+  });
+  mocapMock.command = {
+    actions: [],
+    leftHand: { x: 0.39, y: 0.36, state: 'unknown', side: 'left' },
+    primaryHand: { x: 0.39, y: 0.36, state: 'unknown', side: 'left' },
+    rightHand: null,
+  };
+  mocapMock.receivedAtMs += 1;
+  await act(async () => {
+    rerender(<ChildMotionWarmupDemo />);
+  });
+  mocapMock.command = {
+    actions: [],
+    leftHand: { x: 0.31, y: 0.34, state: 'unknown', side: 'left' },
+    primaryHand: { x: 0.31, y: 0.34, state: 'unknown', side: 'left' },
+    rightHand: null,
+  };
+  mocapMock.receivedAtMs += 1;
+  await act(async () => {
+    rerender(<ChildMotionWarmupDemo />);
+  });
+
+  await vi.waitFor(() => {
+    expect(screen.getByRole('heading', { name: '挥动右手' })).toBeTruthy();
+  });
+
+  mocapMock.command = {
+    actions: ['right_hand_wave'],
+    leftHand: null,
+    primaryHand: { x: 0.64, y: 0.35, state: 'unknown', side: 'right' },
+    rightHand: { x: 0.64, y: 0.35, state: 'unknown', side: 'right' },
+  };
+  mocapMock.receivedAtMs += 1;
+  await act(async () => {
+    rerender(<ChildMotionWarmupDemo />);
+  });
+
+  await vi.waitFor(() => {
+    expect(screen.getByRole('heading', { name: '原地跳一下' })).toBeTruthy();
+  });
+  await act(async () => {
+    vi.advanceTimersByTime(720);
+    await vi.runOnlyPendingTimersAsync();
+    unmount();
+  });
+  vi.useRealTimers();
+});
+
+test('connects camera stream and releases it on unmount', async () => {
+  const stopTrack = vi.fn();
+  const stream = {
+    getTracks: () => [
+      {
+        stop: stopTrack,
+      },
+    ],
+  } as unknown as MediaStream;
+  const getUserMedia = vi.fn().mockResolvedValue(stream);
+  const play = vi
+    .spyOn(HTMLMediaElement.prototype, 'play')
+    .mockResolvedValue(undefined);
+  Object.defineProperty(navigator, 'mediaDevices', {
+    configurable: true,
+    value: {
+      getUserMedia,
+    },
+  });
+
+  const { unmount } = render(<ChildMotionWarmupDemo />);
+
+  expect(screen.queryByText('摄像头暂不可用，已切换到本地演示')).toBeNull();
+  expect(screen.getByText('动作数据已连接，等待识别')).toBeTruthy();
+  await vi.waitFor(() => {
+    expect(getUserMedia).toHaveBeenCalledWith({
+      audio: false,
+      video: {
+        facingMode: 'user',
+      },
+    });
+    expect(play).toHaveBeenCalled();
+  });
+
+  unmount();
+
+  expect(stopTrack).toHaveBeenCalled();
+});
@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  applyChildMotionWarmupCompletion,
+  CHILD_MOTION_CENTER_X,
+  CHILD_MOTION_WARMUP_STEPS,
+  createEmptyChildMotionCalibration,
+  getChildMotionWarmupStep,
+  isAvatarOnWarmupTarget,
+  resolveNextChildMotionWarmupStep,
+} from './childMotionWarmupModel';
+
+describe('childMotionWarmupModel', () => {
+  it('keeps the confirmed warmup order as a strict state chain', () => {
+    expect(CHILD_MOTION_WARMUP_STEPS.map((step) => step.id)).toEqual([
+      'center_arrive',
+      'wave_greeting',
+      'warmup_intro',
+      'move_left',
+      'return_center_1',
+      'move_right',
+      'return_center_2',
+      'wave_left_hand',
+      'wave_right_hand',
+      'jump_once',
+      'warmup_finish',
+      'level_select',
+      'play_placeholder',
+    ]);
+    expect(resolveNextChildMotionWarmupStep('center_arrive')).toBe(
+      'wave_greeting',
+    );
+    expect(resolveNextChildMotionWarmupStep('level_select')).toBe(
+      'play_placeholder',
+    );
+  });
+
+  it('checks position completion against the active green ring target', () => {
+    expect(
+      isAvatarOnWarmupTarget(
+        getChildMotionWarmupStep('center_arrive'),
+        CHILD_MOTION_CENTER_X,
+      ),
+    ).toBe(true);
+    expect(
+      isAvatarOnWarmupTarget(getChildMotionWarmupStep('move_left'), 0.66),
+    ).toBe(false);
+  });
+
+  it('records session-only calibration values from completed steps', () => {
+    const empty = createEmptyChildMotionCalibration();
+    const withLeft = applyChildMotionWarmupCompletion('move_left', empty, {
+      type: 'position',
+      avatarX: 0.34,
+    });
+    const withRight = applyChildMotionWarmupCompletion('move_right', withLeft, {
+      type: 'position',
+      avatarX: 0.66,
+    });
+    const withLeftHand = applyChildMotionWarmupCompletion(
+      'wave_left_hand',
+      withRight,
+      {
+        type: 'left-hand',
+        path: [
+          { x: 0.3, y: 0.4 },
+          { x: 0.34, y: 0.32 },
+        ],
+      },
+    );
+    const completed = applyChildMotionWarmupCompletion(
+      'jump_once',
+      withLeftHand,
+      {
+        type: 'jump',
+        jumpSpace: 0.14,
+      },
+    );
+
+    expect(completed.leftBoundary).toBeCloseTo(0.16);
+    expect(completed.rightBoundary).toBeCloseTo(0.16);
+    expect(completed.leftHandPath).toHaveLength(2);
+    expect(completed.jumpSpace).toBe(0.14);
+  });
+});
--- a/Show More
+++ b/Show More