@skillbuilder/miniapp-simulator 0.2.7 → 0.2.9

package/README.md

@@ -3,10 +3,27 @@
 技术栈无关的小应用 PC 模拟器 SDK，支持 iframe 预览和 Electron webview 审核场景。
 模拟器默认**无贴图外壳**（`phoneFrame: false`），保留创作发布标准深色圆角设备边框；需要 iPhone / Nexus 贴图壳时显式传 `phoneFrame`。默认开启 `stageFit` 自适应撑满挂载区域；手动拖拽缩放需传 `stageFit: { resizeHandle: true }`。
 
+## Mars 桌面操作
+
+Mars 的 Remote Runtime 在手机壳外提供「键位」「逆时针旋转 90°」与「顺时针旋转 90°」按钮。其他业务线不显示这些入口；SDK 的 `desktopControls` 默认关闭。
+
+键位面板为可拖拽悬浮窗，打开和关闭均保持手机大小与位置不变。Remote 模式下挂在接入页面的 `document.body`，可拖出模拟器挂载区域，移动范围为浏览器可视区域；位置在当前实例中保留。面板界面、拖拽和键位编辑逻辑随现有 `runtime.js` 一起远程发布，薄 SDK 提供挂载和通信。服务清单负责选择 Runtime 页面；页面加载的 Runtime entry 将自身 `import.meta.url` 通过现有握手的 `runtimeModuleUrl` 返回，接入页面按需导入这一资源中的面板视图。
+
+1. 打开「键位」，选择「添加映射」，在手机画面中点击一个位置或拖动框选区域。
+2. 按下要绑定的字母、数字、方向键或空格。区域映射使用所选区域的中心作为触点。
+3. 普通按钮选择「按住区域」；方向盘、摇杆选择「拖动并保持」，再点选拖动终点。
+4. 勾选顶部「启用按键映射」，点击右上角「×」关闭面板。按住按键保持触点，松开只释放该键；鼠标和其他按键可同时操作。
+
+例如，油门和刹车可分别绑定 W、S；左转和右转可分别绑定 A、D 的拖动路径。每组映射独立配置，不依赖游戏名称或元素 ID，最多支持 16 组。短按区域支持点击，拖动映射在约 120ms 内移动到终点并保持。输入框、组合输入和 Ctrl / Command / Alt / Shift 快捷键保留浏览器行为。
+
+「逆时针旋转 90°」和「顺时针旋转 90°」每点击一次，将手机壳、内容和 iframe 一起按对应方向旋转 90°；同方向连续四次回到原位。iframe 的逻辑宽高保持不变，旋转时释放活动触点。竖直摆放时按钮位于手机左侧纵排，质量分位于右侧；横向摆放时按钮位于手机下方横排，质量分位于按钮下方，正文保持正向且可滚动。映射坐标相对于内容视口保存，旋转和缩放均保持区域位置；页面自身布局变化后需检查并重选区域。关闭映射、窗口失焦、页面隐藏、内容重载和销毁均清理活动触点。映射在当前模拟器实例中保留，重新创建实例需重新配置。
+
 ```bash
-pnpm --filter @skillbuilder/miniapp-simulator run playground
+pnpm run dev:simulator
 ```
 
+在仓库根目录启动后访问 `http://localhost:5176/simulator`。区域映射、触点时序和远程部署方案见 [桌面手势与按键映射设计](./docs/desktop-gesture-design.redoc.xml)。
+
 Smoke 联调：`testsuits/miniapp-simulator-sdk-smoke` 以 ESM `import` 引用本包 `lib/`；改源码后 `pnpm --filter @skillbuilder/miniapp-simulator run build:npm`，再 `pnpm --filter miniapp-simulator-sdk-smoke dev` 即可。
 
 **设备能力封印**由本包自维护：封印 IIFE 以本地文件形式存放在