@skillbuilder/miniapp-simulator 0.2.7 → 0.2.8

package/lib/remote-client.js

@@ -1,6 +1,6 @@
-import { R as r, a as O, c as e } from "./client-BjYHK9LR.mjs";
+import { R as r, a as O, c as e } from "./client-C59iNO5u.mjs";
 import { B as s, M as _ } from "./options-B34ipLmF.mjs";
-import { M } from "./index-CqClPZVv.mjs";
+import { M } from "./index-BSj1bmle.mjs";
 export {
   s as BusinessLine,
   _ as MINIAPP_SCREENSHOT_ERROR_CODE,

package/lib/types/core/simulator.d.ts

@@ -1,7 +1,9 @@
+import type { KeyboardPanelHost } from "../gesture/keyboard-panel";
 import type { MiniAppSimulator as MiniAppSimulatorInterface, MiniAppSimulatorOptions } from "../types";
 export declare function createMiniAppSimulator(options: MiniAppSimulatorOptions): MiniAppSimulatorInterface;
 /** @internal 远程 Runtime 注入服务端托管资源；不属于接入方配置。 */
 export declare function createRuntimeMiniAppSimulator(options: MiniAppSimulatorOptions, runtimeOptions: {
+    keyboardPanelHost?: KeyboardPanelHost;
     requestManagerFrameUrl: string;
     gateways?: Record<string, string>;
     businessLine?: string;

package/lib/types/gesture/host-bus.d.ts

@@ -9,8 +9,11 @@
  *
  * Plugin 通过 `install(ctx)` 订阅事件并往 iframe 发协议消息。
  */
+import type { ScreenRotationDirection } from "../utils/screen-coordinates";
 import type { GestureDispatchInput, GestureDispatchResult, GestureGuestChannel, GestureHostPlugin, GestureSharedState } from "./types";
 export interface GestureHostBusOptions {
+    /** 外置横竖屏控件，由已启用桌面控件的宿主提供。 */
+    rotateScreen?: (direction: ScreenRotationDirection) => void;
     /** 内容载体元素（iframe 或 webview）；仅用于坐标换算与聚焦 */
     element: HTMLElement;
     /** host↔guest 介质通道（发送/回包/聚焦/cursor），由各 ContentHost 注入 */
@@ -39,12 +42,25 @@ export declare class GestureHostBus {
     /** light DOM 移入边界（shadow host），补 Shadow 穿透场景 */
     private readonly hoverEnterTarget;
     private readonly debug;
+    private readonly rotateScreen?;
     private readonly rawHandlers;
     private readonly logicHandlers;
     private readonly plugins;
+    private readonly pluginSubscriptions;
     /** 跨 plugin 共享状态 */
     readonly state: GestureSharedState;
+    private readonly inputScheduler;
+    private keyboardCaptureEnabled;
+    private keyboardCodes;
+    private guestInputPossible;
+    private hostFocusIntentAt;
+    /** 原生捕获与已提交手势分离，等待 guest 水位时也能接收 move/up。 */
+    private physicalPressed;
+    private readonly nativePrevention;
     private destroyed;
+    private resettingGuest;
+    /** 鼠标、滚轮和键盘各自维护序列，这里聚合 guest 可见的所有触点。 */
+    private readonly activeTouches;
     /** 当前 mouse 是否正在捕获 mousemove（mousedown 后绑定，mouseup 后解绑） */
     private capturingWindowMove;
     /** 业务 plugin 可临时覆盖 cursor，nul 时回到默认 */
@@ -72,13 +88,15 @@ export declare class GestureHostBus {
      * 或坐标缩放细节。
      */
     dispatch(input: GestureDispatchInput): Promise<GestureDispatchResult>;
+    /** 结束鼠标、键盘等输入源的活动触点，供切页和旋转前调用。 */
+    cancelActiveGestures(): void;
     /**
      * 由宿主在 iframe.onload + receiver runtime 注入完成后调用。
-     * 触发 "iframe:ready" 逻辑事件，需要 receiver 就绪后才能 send 的 plugin
-     * （如 `selection-disabler`）可通过 `ctx.hook("iframe:ready", ...)` 监听。
+     * 需要 receiver 就绪后发送配置的插件订阅 iframe:ready。
      */
     notifyIframeReady(): void;
     destroy(): void;
+    private uninstallPlugin;
     private makeContext;
     private subscribeRaw;
     private subscribeLogic;
@@ -101,11 +119,18 @@ export declare class GestureHostBus {
      * 回退 hoverTrackTarget。contentRoot 在 stageFit 缩放 + flex 布局下 rect 可能偏移/塌缩。
      */
     private get hoverRegion();
+    private guestHasFocus;
+    private focusGuest;
+    private discardPendingInputs;
+    private preventNative;
     private onMouseDown;
     private onMouseMoveDragging;
     private onMouseUp;
     private onWheel;
+    private onVisibilityChange;
     private onWindowBlur;
+    private onHostFocusIntent;
+    private applyGuestMessage;
     /** guest 内表单控件 focus 后，把宿主焦点切到载体，键盘输入才能进小应用 */
     private onGuestInbound;
     private bindCapturingWindowMove;

package/lib/types/gesture/input-scheduler.d.ts

@@ -0,0 +1,29 @@
+export declare class GestureInputScheduler {
+    private readonly options;
+    private tasks;
+    private nextOrdinal;
+    private nextRequest;
+    private request;
+    private watermark;
+    private running;
+    private applyingAt;
+    private wake;
+    private readonly waiters;
+    generation: number;
+    constructor(options: {
+        needsBarrier: () => boolean;
+        sendBarrier: (requestId: number, generation: number) => void;
+        onError: (error: unknown) => void;
+    });
+    time(): number;
+    enqueue(run: () => void, issuedAt?: number, fromGuest?: boolean, cleanupOnly?: boolean): () => void;
+    acknowledge(requestId: unknown, generation: unknown, issuedAt: unknown): void;
+    /** 关闭键盘输入时撤销旧 guest 的确认，保留鼠标释放和滚轮截止点。 */
+    endGuestStream(): void;
+    cancel(): void;
+    /** 等待当前时刻已经生成的输入；未来的长按/滚轮截止点不阻塞调用。 */
+    settled(): Promise<void>;
+    private hasDueTasks;
+    private settle;
+    private pump;
+}

package/lib/types/gesture/keyboard-panel-view.d.ts

@@ -0,0 +1,16 @@
+export { keyboardPanelCommandNeedsGameFocus } from "./keyboard-panel";
+import type { KeyboardPanelCommand, KeyboardPanelConnection } from "./keyboard-panel";
+export declare const KEYBOARD_UI_STYLES = "\n  [data-mini-app-keyboard-ui],[data-mini-app-keyboard-ui] * {-webkit-user-select:none;user-select:none}\n  [data-mini-app-keyboard-ui] button,[data-mini-app-keyboard-ui] select {font:inherit;cursor:pointer;color:inherit;background:#273244;border:1px solid #526078;border-radius:6px;padding:6px 9px}\n  [data-mini-app-keyboard-ui] button:focus-visible,[data-mini-app-keyboard-ui] select:focus-visible {outline:2px solid #60a5fa;outline-offset:2px}\n  [data-mini-app-keyboard-ui] button:disabled {opacity:.45;cursor:default}\n  [data-mini-app-keyboard-ui] [data-mini-app-keyboard-panel] {width:296px;max-width:calc(100vw - 24px);box-sizing:border-box;position:fixed;z-index:2147483000;font:12px/1.5 system-ui,sans-serif;color:#e5e7eb;cursor:default;background:#172033;padding:14px;border:1px solid #526078;border-radius:10px;box-shadow:0 6px 24px #0005;max-height:calc(100vh - 24px);overflow:auto}\n  [data-mini-app-keyboard-ui] [data-mini-app-keyboard-panel-handle] {display:flex;align-items:center;justify-content:space-between;gap:12px;cursor:grab;touch-action:none;user-select:none;position:sticky;top:-14px;background:#172033;padding:8px 0;z-index:1}\n  [data-mini-app-keyboard-ui] [data-mini-app-keyboard-panel-handle] span {font-size:11px;color:#a6b4c9}\n  [data-mini-app-keyboard-ui] [data-key-code] {display:flex;align-items:center;gap:6px;flex-wrap:wrap;margin:10px 0;padding:8px 0;border-bottom:1px solid #334155}\n  [data-mini-app-keyboard-ui] [data-key-label] {min-width:34px;font-weight:600}\n  [data-mini-app-keyboard-ui] [data-mini-app-keyboard-panel] small {flex:1;color:#a6b4c9;font-size:11px}\n  [data-mini-app-keyboard-ui] [data-mini-app-keyboard-panel] p {margin:8px 0;color:#c2cddd;font-size:12px}\n  [data-mini-app-keyboard-ui] [data-mapping-notice] {padding:8px;background:#253650;border-radius:6px}\n";
+export interface KeyboardPanelViewOptions {
+    root: HTMLElement;
+    onCommand: (command: KeyboardPanelCommand) => void;
+    /** 当前视图 window 的 client 坐标，跨 iframe 投影由调用者完成。 */
+    getAnchor: () => {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+}
+/** 面板渲染状态并转发自身焦点内的按键；游戏选区和触点由 gesture plugin 管理。 */
+export declare function createKeyboardPanelView(options: KeyboardPanelViewOptions): KeyboardPanelConnection;

package/lib/types/gesture/keyboard-panel.d.ts

@@ -0,0 +1,54 @@
+/** 可序列化的键位面板视图；游戏触点和选区状态由 gesture plugin 持有。 */
+export interface KeyboardPanelState {
+    open: boolean;
+    enabled: boolean;
+    available: boolean;
+    busy: boolean;
+    notice: string;
+    bindings: Array<{
+        code: string;
+        mode: "hold" | "drag";
+        isRegion: boolean;
+    }>;
+    anchor: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+    viewport: {
+        width: number;
+        height: number;
+    };
+}
+export type KeyboardPanelCommand = {
+    type: "add" | "cancel" | "close" | "outside";
+} | {
+    type: "rebind" | "pick" | "remove" | "destination";
+    code: string;
+} | {
+    type: "mode";
+    code: string;
+    mode: "hold" | "drag";
+} | {
+    type: "enable";
+    enabled: boolean;
+    issuedAt: number;
+    sequence: number;
+} | {
+    type: "key";
+    eventName: "keydown" | "keyup" | "cancel" | "focusout";
+    code: string;
+    repeat: boolean;
+    issuedAt: number;
+    sequence: number;
+};
+export interface KeyboardPanelConnection {
+    update(state: KeyboardPanelState): void;
+    dispose(): void;
+}
+/** Runtime 的宿主提供序列化通道；本地 SDK 使用同页面板视图。 */
+export interface KeyboardPanelHost {
+    mount(onCommand: (command: KeyboardPanelCommand) => void): KeyboardPanelConnection;
+}
+export declare function keyboardPanelCommandNeedsGameFocus(command: KeyboardPanelCommand): boolean;

package/lib/types/gesture/plugins/index.d.ts

@@ -1,18 +1,10 @@
 /**
- * 内置的 host-side gesture plugin 工厂集合。
+ * 内置 host 插件按输入互斥与状态依赖排序：
+ * wheel-pinch → multi-touch-switch / pinch / rotate → touch-emitter → tap / long-press /
+ * double-tap → wheel-scroll → selection-disabler → multi-touch-hint。
  *
- * GestureHostBus 默认会安装所有这些 plugin（按以下顺序）：
- *   1. multi-touch-switch / pinch / rotate ── 控制 state.multiTouchMode（必须在 touch-emitter 前）
- *   2. touch-emitter                       ── 派发 touch 事件（读 state 决定单/双指几何）
- *   3. tap                                  ── 短按 → mini-app:tap（receiver 合成 click）
- *   4. long-press                          ── 长按 → mini-app:longpress（contextmenu）
- *   5. double-tap                          ── hook tap → mini-app:dblclick
- *   6. wheel-scroll                        ── 滚轮 → mini-app:wheel
- *   7. selection-disabler                  ── iframe body user-select: none
- *   8. multi-touch-hint                    ── 状态条 + 副触点圆点
- *
- * 注：手指圆点（hover/press 指针）已从 plugin 上移为 gesture 核心内置 `TouchCursor`
- * （见 `../touch-cursor.ts`），由 GestureHostBus 直接持有，圆点显示不再走事件管线。
+ * wheel-pinch 在鼠标按下前结束滚轮序列；模式插件在 touch-emitter 之前确定双指基点。
+ * TouchCursor 负责单指与悬停，多指提示读取 touch:points 绘制实际触点。
  */
 export { createTouchEmitterPlugin } from "./touch-emitter";
 export { createMultiTouchSwitchPlugin, createPinchPlugin, createRotatePlugin, } from "./multi-touch-switch";
@@ -20,8 +12,13 @@ export { createTapPlugin } from "./tap";
 export { createLongPressPlugin } from "./long-press";
 export { createDoubleTapPlugin } from "./double-tap";
 export { createWheelScrollPlugin } from "./wheel-scroll";
+export { createWheelPinchPlugin } from "./wheel-pinch";
 export { createSelectionDisablerPlugin } from "./selection-disabler";
 export { createMultiTouchHintPlugin } from "./multi-touch-hint";
+import type { KeyboardPanelHost } from "../keyboard-panel";
 import type { GestureHostPlugin } from "../types";
 /** 一次性生成全套内置 plugin（mode-switch 必须在 touch-emitter 之前注册） */
-export declare function createDefaultHostPlugins(): GestureHostPlugin[];
+export declare function createDefaultHostPlugins(options?: {
+    keyboardMapping?: boolean;
+    keyboardPanelHost?: KeyboardPanelHost;
+}): GestureHostPlugin[];

package/lib/types/gesture/plugins/keyboard-touch.d.ts

@@ -0,0 +1,4 @@
+import type { KeyboardPanelHost } from "../keyboard-panel";
+import type { GestureHostPlugin } from "../types";
+/** 通用区域/拖动映射；每个按键和鼠标分别维护触点生命周期。 */
+export declare function createKeyboardTouchPlugin(panelHost?: KeyboardPanelHost): GestureHostPlugin;

package/lib/types/gesture/plugins/multi-touch-hint.d.ts

@@ -1,11 +1,3 @@
-/**
- * MultiTouchHintPlugin — 双指模式可视化提示。
- *
- * 当任意 MultiTouchSwitch/Pinch/Rotate emit "multitouch:enter" 时：
- *   - 顶部加状态条，提示当前模式（mirror / pinch / rotate）
- *   - 在副触点位置画一个圆点，随鼠标移动
- *
- * leave 时清掉两者。
- */
 import type { GestureHostPlugin } from "../types";
+/** 圆点直接读取派发坐标，支持鼠标和触控板。 */
 export declare function createMultiTouchHintPlugin(): GestureHostPlugin;

package/lib/types/gesture/plugins/multi-touch-switch.d.ts

@@ -12,7 +12,7 @@
 import type { GestureHostPlugin } from "../types";
 /** Shift+拖动 = 镜像双指（经典 hammerjs 风格） */
 export declare function createMultiTouchSwitchPlugin(): GestureHostPlugin;
-/** Alt+拖动 = 捏合双指（真实 pinch，副触点直接对称） */
+/** Alt / Option+拖动 = 双指围绕固定中心捏合。 */
 export declare function createPinchPlugin(): GestureHostPlugin;
 /** Ctrl+拖动 = 旋转双指（副触点关于 base 旋转 180°） */
 export declare function createRotatePlugin(): GestureHostPlugin;

package/lib/types/gesture/plugins/touch-emitter.d.ts

@@ -1,11 +1,3 @@
-/**
- * TouchEmitterPlugin — 核心 touch 派发器。
- *
- * 监听 PointerSnapshot 的 down/move/up/leave/blur，转换为 `mini-app:touch` 消息发到 iframe。
- * 根据 state.isMultiTouch + state.multiTouchMode 决定派 1 / 2 个触点及其几何算法：
- *   - "mirror"：副触点 = 主触点关于 base 对称 + MULTI_TOUCH_OFFSET 外推（默认双指）
- *   - "pinch"：副触点 = 主触点关于 base 真实对称（无偏移，模拟捏合）
- *   - "rotate"：副触点 = 主触点关于 base 旋转 180°
- */
 import type { GestureHostPlugin } from "../types";
+/** 鼠标拖拽的单 / 双指触摸；基点由多指模式插件确定。 */
 export declare function createTouchEmitterPlugin(): GestureHostPlugin;

package/lib/types/gesture/plugins/wheel-pinch.d.ts

@@ -0,0 +1,3 @@
+import type { GestureHostPlugin } from "../types";
+/** 触控板 ctrl+wheel、鼠标 Alt+wheel、WebKit gesture 统一生成双指序列。 */
+export declare function createWheelPinchPlugin(): GestureHostPlugin;

package/lib/types/gesture/plugins/wheel-scroll.d.ts

@@ -5,7 +5,7 @@
  * 本 plugin 监听 overlay 的 wheel 事件，转发到 iframe 内（receiver 端 WheelDispatchPlugin
  * 派发原生 WheelEvent + scrollBy fallback）。
  *
- * 注意：Alt + wheel 不在本 plugin 处理（由 PinchPlugin 拦截作为缩放）。
+ * Ctrl / Alt + wheel 由 wheel-pinch 处理为双指缩放。
  */
 import type { GestureHostPlugin } from "../types";
 export declare function createWheelScrollPlugin(): GestureHostPlugin;

package/lib/types/gesture/touch-cursor.d.ts

@@ -39,6 +39,8 @@ export declare class TouchCursor {
     private destroyed;
     /** DevTools 审查等场景暂时禁止显示/跟随，避免挡住 Elements 选点 */
     private suppressed;
+    private multiTouch;
+    private inside;
     private visible;
     private pressed;
     private hot;
@@ -69,6 +71,8 @@ export declare class TouchCursor {
     private tickHot;
     /** DevTools 审查 / 权限弹窗 / 元素选取等场景：隐藏圆点并暂停跟随，避免干扰上层交互 */
     setSuppressed(suppressed: boolean): void;
+    /** 多指圆点由手势插件按实际触点坐标绘制。 */
+    setMultiTouch(active: boolean): void;
     private onMove;
     private onLeave;
     private onDown;

package/lib/types/gesture/touch-sequence.d.ts

@@ -0,0 +1,12 @@
+import type { GestureHostContext, GesturePoint, ModifierKeys, PointerSnapshot } from "./types";
+/** 一段触摸序列；两个输入设备共用 touches / changedTouches 的生命周期。 */
+export declare class TouchSequence {
+    private readonly ctx;
+    private points;
+    private modifiers;
+    constructor(ctx: GestureHostContext);
+    update(next: GesturePoint[], modifiers: ModifierKeys): void;
+    finish(cancel?: boolean): void;
+    private send;
+}
+export declare function gesturePoint(element: HTMLElement, snap: PointerSnapshot, identifier: number, x?: number, y?: number): GesturePoint;

package/lib/types/gesture/types.d.ts

@@ -6,6 +6,7 @@
  * - host 端 plugin 监听原始事件并 send 给 iframe，receiver 端 plugin 派发对应 DOM 事件
  * - 跨 plugin 通过共享状态 + 逻辑事件 emit/on 协作
  */
+import type { ScreenRotationDirection } from "../utils/screen-coordinates";
 export interface GesturePoint {
     identifier: number;
     clientX: number;
@@ -27,7 +28,7 @@ export interface ModifierKeys {
  */
 export interface PointerSnapshot {
     kind: "down" | "move" | "up" | "leave" | "wheel" | "blur";
-    /** iframe CSS 坐标空间（已做 transform scale 修正） */
+    /** iframe CSS 坐标空间（已修正设备缩放与屏幕旋转） */
     iframeX: number;
     iframeY: number;
     /** 宿主视口坐标（用于 overlay 上画 UI） */
@@ -72,7 +73,7 @@ export interface GestureDispatchResult {
     segments?: number;
     durationMs?: number;
 }
-export type GestureBusMessage = TouchMessage | WheelMessage | TapMessage | LongPressMessage | DoubleTapMessage | CursorQueryMessage | SelectionMessage;
+export type GestureBusMessage = TouchMessage | WheelMessage | TapMessage | LongPressMessage | DoubleTapMessage | CursorQueryMessage | SelectionMessage | KeyboardCaptureMessage | InputBarrierMessage;
 export interface TouchMessage {
     type: "mini-app:touch";
     eventName: "touchstart" | "touchmove" | "touchend" | "touchcancel";
@@ -117,6 +118,17 @@ export interface CursorReplyMessage {
     queryId: number;
     cursor: string;
 }
+export interface KeyboardCaptureMessage {
+    type: "mini-app:keyboard-capture";
+    codes: string[];
+    /** 由 host bus 填充；取消/重载后拒绝旧输入。 */
+    generation?: number;
+}
+export interface InputBarrierMessage {
+    type: "mini-app:input-barrier";
+    requestId: number;
+    generation: number;
+}
 export interface SelectionMessage {
     type: "mini-app:selection";
     enabled: boolean;
@@ -145,12 +157,7 @@ export interface GestureGuestChannel {
     /** 读 host 视口坐标下 guest 元素的 computed cursor（hot 判定）；不支持返回 undefined */
     readCursorAt(hostX: number, hostY: number): string | undefined;
 }
-/**
- * 双指模式下的副触点几何算法。
- * - "mirror"：副触点为主触点关于 base 的对称点（再外推固定偏移）—— 经典 shift 双指
- * - "pinch"：副触点为主触点关于 base 的真实对称点（无偏移）—— 模拟捏合
- * - "rotate"：副触点为主触点关于 base 旋转 180° 后的点 —— 模拟双指旋转
- */
+/** 双指模式：镜像 / 捏合 / 旋转，触点围绕固定基点对称且初始间距非零。 */
 export type MultiTouchMode = "mirror" | "pinch" | "rotate";
 export interface GestureSharedState {
     /** 鼠标主按键是否处于按下态 */
@@ -179,8 +186,25 @@ export type RawEventName = PointerSnapshot["kind"];
 export type RawEventHandler = (ev: PointerSnapshot) => void;
 export type LogicEventHandler = (...args: unknown[]) => void;
 export interface GestureHostContext {
+    /** 取消活动手势后旋转整台设备，保持逻辑视口尺寸；仅启用桌面控件时提供。 */
+    rotateScreen?: (direction: ScreenRotationDirection) => void;
+    /** 同步恢复 guest 原生键盘焦点，保留当前活动触点。 */
+    focusGuest(): void;
     /** 订阅原始指针事件 */
-    on(event: RawEventName, handler: RawEventHandler): () => void;
+    on(event: RawEventName, handler: RawEventHandler, options?: {
+        /** 在原生事件返回前同步拦截默认行为；语义处理可等待 guest 水位。 */
+        preventDefault?: (snapshot: PointerSnapshot) => boolean;
+    }): () => void;
+    /** 在跨窗口输入水位内执行状态变更。 */
+    orderInput(run: () => void, issuedAt?: number, options?: {
+        cleanupOnly?: boolean;
+    }): void;
+    /** 按源输入时间调度可取消的截止点（例如长按）。 */
+    scheduleInput(run: () => void, dueAt: number, options?: {
+        cleanupOnly?: boolean;
+    }): () => void;
+    /** 当前提交输入的 epoch 时间；原生回调中返回当前时间。 */
+    inputTime(): number;
     /** 跨 plugin 协作：触发逻辑事件 */
     emit(event: string, ...args: unknown[]): void;
     /** 订阅逻辑事件（例如 'tap' / 'longpress' / 'pinch' / 'rotate'） */

package/lib/types/host/shadow-host.d.ts

@@ -7,11 +7,13 @@
  *       #shadow-root（shadow=true 时）
  *         <style> base reset </style>
  *         bounds（.dms-bounds，stageFit 的可用区域 / 默认 bounds）
- *           stage（.dms-stage，渲染器实际挂载点，等价于旧的 container）
+ *           stage（.dms-stage，缩放与旋转后的占位）
+ *             device（实际设备，包含手机壳与完整内容）
  *
  * shadow=false 时不创建 shadow root，bounds/stage 直接挂在 host 的 light DOM 下，
  * 仅依赖内联样式（手机壳 / 内容层 / 手柄本身就是内联样式，自定义元素自带 :host 样式）。
  */
+import type { ScreenRotationDirection } from "../utils/screen-coordinates";
 /** 挂载目标：CSS 选择器字符串或 HTMLElement */
 export type MiniAppMountTarget = string | HTMLElement;
 export interface CreateShadowHostOptions {
@@ -27,20 +29,28 @@ export interface MiniAppShadowHost {
     shadowRoot: ShadowRoot | null;
     /** stageFit 的默认可用区域（bounds） */
     bounds: HTMLElement;
-    /** 渲染器实际挂载点（等价于旧 container） */
+    /** stageFit 缩放的设备占位，旋转时交换宽高 */
     stage: HTMLElement;
+    /** 渲染器实际挂载点，逻辑宽高不随屏幕旋转改变 */
+    device: HTMLElement;
     /** 宿主侧 overlay（如 toast）应挂载到的根：shadowRoot 或 host */
     overlayRoot: ShadowRoot | HTMLElement;
     /**
-     * 与设备画布并排的侧栏槽位（评测面板等）。
+     * 评测面板等内容的独立槽位：竖直摆放时在设备右侧，横向摆放时在设备下方。
      *
      * 默认宽度为 0 且不渲染，只有调用 setSidePanelWidth 打开后才占位。
      * 走分栏而非浮层：浮层会直接盖住设备，而审核页把挂载点限制成手机尺寸，
      * 盖住后审核员既看不到小工具也点不到它。
      */
     sidePanel: HTMLElement;
-    /** 设置侧栏最小/最大宽度；传 0 收起。bounds 自动让出对应宽度。 */
+    /** 设置竖直摆放时侧栏最小/最大宽度；传 0 收起。bounds 自动让出面板空间。 */
     setSidePanelWidth(width: number, maxWidth?: number): void;
+    /** 桌面工具栏的空间只影响宿主布局。 */
+    setDesktopControls(enabled: boolean): void;
+    /** 整台设备每次按指定方向旋转 90°，四次回到原位，不改变 guest 逻辑尺寸。 */
+    rotateScreen(direction: ScreenRotationDirection): void;
+    /** 渲染器挂载或逻辑尺寸改变后同步设备占位。 */
+    syncDeviceLayout(): void;
     /** 销毁：移除创建的宿主元素 */
     destroy(): void;
 }

package/lib/types/inspector/host-inspector.d.ts

@@ -86,7 +86,7 @@ export declare class HostInspector {
     private selectionRect;
     /**
      * 宿主视口坐标 → iframe 内容元素。
-     * 与手势模块 `readCursorAt` 同一套换算：用 offsetWidth/rect.width 修正设备缩放。
+     * 与手势模块共用坐标转换，修正设备缩放和旋转。
      * 同源不可访问（跨源 / webview）时返回 null 并降级告警一次。
      */
     private resolveElement;

package/lib/types/remote/audit-controller.d.ts

@@ -19,6 +19,8 @@ export interface AuditControllerDeps {
     /** Apollo 下发的评测策略原始值；未下发时为 undefined */
     getPolicy(): unknown;
     getInteractionRegions(): readonly HTMLElement[];
+    /** 外层键位面板属于审核操作区域，保护离开倒计时而不增加真实输入次数。 */
+    isExternalInteractionActive?: () => boolean;
     /** 与当前 Runtime release 绑定的独立插件地址。 */
     auditPluginUrl?: string;
     /** 把评测进度 / 报告以事件推给宿主 */

package/lib/types/remote/audit-leave-monitor.d.ts

@@ -3,6 +3,8 @@ export declare function resolveAutoStopOnLeaveMs(value: unknown): number;
 /** 监听稳定的模拟器区域，不进入 guest DOM，也不把 iframe 内部切换当作离开。 */
 export declare function createAuditLeaveMonitor(options: {
     regions: readonly HTMLElement[];
+    /** 已验证宿主通道报告的外层面板悬停/焦点；不作为游戏输入证据。 */
+    isExternalInside?: () => boolean;
     delayMs: number;
     onCountdown(seconds: number | null): void;
     onTimeout(): void;

package/lib/types/remote/client.d.ts

@@ -109,5 +109,7 @@ export interface RemoteMiniAppSimulator {
     destroy(reason?: string): void;
 }
 export declare function createRemoteMiniAppSimulator(input: RemoteMiniAppSimulatorOptions): RemoteMiniAppSimulator;
+/** @internal 地址由当前 Runtime entry 经握手端口提供，仅在同一会话内使用。 */
+export declare function resolveRuntimeModuleUrl(ready: RemoteSimulatorReadyMessage, runtimeDocumentUrl: URL): URL;
 /** @internal Exported for deterministic retry tests; not part of the package public entry. */
 export declare function resolveRuntimeUrl(serviceUrls: URL[], loadTiming: RemoteLoadTiming): Promise<URL>;

package/lib/types/remote/keyboard-panel-host.d.ts

@@ -0,0 +1,19 @@
+import type { KeyboardPanelHost, keyboardPanelCommandNeedsGameFocus } from "../gesture/keyboard-panel";
+import type { createKeyboardPanelView } from "../gesture/keyboard-panel-view";
+import type { RemoteKeyboardPanelCommandMessage, RemoteKeyboardPanelPresenceMessage, RemoteKeyboardPanelStateMessage } from "./protocol";
+export type RemoteRuntimeModule = {
+    createKeyboardPanelView: typeof createKeyboardPanelView;
+    keyboardPanelCommandNeedsGameFocus: typeof keyboardPanelCommandNeedsGameFocus;
+};
+/** Runtime 每个 gesture controller 独立注册；触点和编辑状态始终留在 Runtime。 */
+export declare function createRuntimeKeyboardPanelHost(port: MessagePort, sessionId: string): {
+    host: KeyboardPanelHost;
+    receive(message: RemoteKeyboardPanelCommandMessage | RemoteKeyboardPanelPresenceMessage): void;
+    isActive: () => boolean;
+    destroy(): void;
+};
+/** 浮窗挂在 Remote Client 页面，位置、拖动和焦点边界使用外层 viewport。 */
+export declare function createClientKeyboardPanelHost(iframe: HTMLIFrameElement, send: (message: RemoteKeyboardPanelCommandMessage | RemoteKeyboardPanelPresenceMessage) => void, loadRuntimeModule: () => Promise<RemoteRuntimeModule>, onError: (error: unknown) => void): {
+    receive(message: RemoteKeyboardPanelStateMessage): void;
+    destroy(): void;
+};

package/lib/types/remote/protocol.d.ts

@@ -1,4 +1,5 @@
 import type { BusinessLine } from "../business-line";
+import type { KeyboardPanelCommand, KeyboardPanelState } from "../gesture/keyboard-panel";
 import type { ManagedRequestChunk, ManagedRequestHeaders, ManagedRequestOptions, ManagedRequestResult } from "../runtime/request/request-types";
 import type { MiniAppContentMode, MiniAppFileMap, MiniAppHostApiRequest, MiniAppInspectorSelectionMode, MiniAppLoadFilesOptions, MiniAppLoadZipOptions, MiniAppRedirectOptions, MiniAppSecurityOptions, MiniAppSimulatorOptions, MiniAppSimulatorRoute, MiniAppViewport } from "../types";
 /**
@@ -14,6 +15,8 @@ export declare const REMOTE_INSPECTOR_PAUSE_RUNTIME_CAPABILITY = "inspectorPause
  * 版本不一致会让老 runtime 直接握手失败，而评测是可选能力，缺失只应降级。
  */
 export declare const REMOTE_AUDIT_CAPABILITY = "audit";
+/** Client 可在外层页面承载 Runtime 的键位编辑浮窗。 */
+export declare const REMOTE_KEYBOARD_PANEL_CAPABILITY = "keyboardPanelPortal";
 export declare const REMOTE_SIMULATOR_CAPABILITIES: string[];
 export type RemoteSimulatorSerializableOptions = Omit<MiniAppSimulatorOptions, "mount" | "appId" | "renderer" | "serviceWorker" | "security" | "jsapi" | "hostApi" | "tracker" | "runtimeLimits" | "onEvent" | "onReady" | "onBeforeLoad" | "onLoad" | "onRenderDone" | "onError" | "onNavigation" | "onConsole" | "onNetwork" | "onDestroy" | "onRouterChange" | "onScreenShot"> & {
     appUrl?: string;
@@ -39,6 +42,7 @@ export interface RemoteSimulatorConnectMessage {
     hostApiStubs: Record<string, {
         toast: string;
     }>;
+    clientCapabilities?: string[];
     options: RemoteSimulatorSerializableOptions;
 }
 /** Mars 队列项提供的稳定业务标识；随评测点位进入 APM，不进入被测 guest。 */
@@ -60,6 +64,8 @@ export interface RemoteSimulatorReadyMessage {
     protocolVersion: number;
     runtimeVersion: string;
     capabilities: string[];
+    /** 当前 Runtime entry 自身的模块地址，供外层页面复用同一资源。 */
+    runtimeModuleUrl?: string;
 }
 export interface RemoteSimulatorRequestMessage {
     type: "request";
@@ -82,6 +88,23 @@ export interface RemoteSimulatorEventMessage {
     event: string;
     payload: unknown;
 }
+export interface RemoteKeyboardPanelStateMessage {
+    type: "keyboard-panel-state";
+    controllerId: string;
+    revision: number;
+    /** null 显式销毁该控制器的浮窗；后续状态不能复活它。 */
+    state: KeyboardPanelState | null;
+}
+export interface RemoteKeyboardPanelCommandMessage {
+    type: "keyboard-panel-command";
+    controllerId: string;
+    command: KeyboardPanelCommand;
+}
+export interface RemoteKeyboardPanelPresenceMessage {
+    type: "keyboard-panel-presence";
+    controllerId: string;
+    active: boolean;
+}
 /** Runtime 请求宿主执行不可序列化的 hostApi handler。 */
 export interface RemoteHostApiRequestMessage {
     type: "host-api-request";
@@ -132,7 +155,7 @@ export interface RemoteHostRequestEventMessage {
 export type RemoteSimulatorPortMessage = {
     type: "worker-visibility";
     visible: boolean;
-} | RemoteSimulatorReadyMessage | RemoteSimulatorRequestMessage | RemoteSimulatorResponseMessage | RemoteSimulatorEventMessage | RemoteHostApiRequestMessage | RemoteHostApiResponseMessage | RemoteHostRequestMessage | RemoteHostRequestResponseMessage | RemoteHostRequestAbortMessage | RemoteHostRequestEventMessage;
+} | RemoteKeyboardPanelStateMessage | RemoteKeyboardPanelCommandMessage | RemoteKeyboardPanelPresenceMessage | RemoteSimulatorReadyMessage | RemoteSimulatorRequestMessage | RemoteSimulatorResponseMessage | RemoteSimulatorEventMessage | RemoteHostApiRequestMessage | RemoteHostApiResponseMessage | RemoteHostRequestMessage | RemoteHostRequestResponseMessage | RemoteHostRequestAbortMessage | RemoteHostRequestEventMessage;
 export type RemoteSimulatorMethod = "load" | "loadZip" | "loadFiles" | "loadApp" | "unload" | "reload" | "setViewport" | "switchContentMode" | "switchPhoneFrame" | "switchDevice" | "setTouchEmulation" | "permissionSheet.show" | "permissionSheet.hide" | "notePreview.update" | "notePreview.updateUser" | "notePreview.updateAppCard" | "widgetCover.update" | "router.redirectTo" | "router.getRoute" | "inspector.enable" | "inspector.disable" | "inspector.toggle" | "inspector.clear" | "inspector.setSelectionMode" | "inspector.getSelectionMode" | "inspector.getSceneTree" | "inspector.selectByRef" | "capture" | "screenShot" | "setAutoScreenShot" | "hostApi.sync" | "hostApi.emit" | "audit.start" | "audit.stop" | "audit.status" | "audit.report" | "audit.setPolicy" | "destroy";
 export interface RemoteLoadZipArgs {
     buffer: ArrayBuffer;

package/lib/types/remote/runtime-entry.d.ts

@@ -1 +1,2 @@
-export {};
+export { keyboardPanelCommandNeedsGameFocus } from "../gesture/keyboard-panel";
+export { createKeyboardPanelView } from "../gesture/keyboard-panel-view";

package/lib/types/remote/runtime.d.ts

@@ -13,4 +13,4 @@ export interface RemoteRuntimeConfig {
     /** 与本 Runtime release 绑定的独立评测插件；仅 Mars 审核会话动态加载。 */
     auditPluginUrl?: string;
 }
-export declare function startRemoteMiniAppSimulatorRuntime(): void;
+export declare function startRemoteMiniAppSimulatorRuntime(runtimeModuleUrl: string): void;

package/lib/types/types/options.d.ts

@@ -487,6 +487,9 @@ export interface MiniAppSimulatorOptions extends MiniAppLifecycleCallbacks {
     debug?: boolean;
     /** 开启鼠标→触摸事件模拟，使桌面端鼠标操作还原真机 touch 行为（显示小手光标与触点圆点） */
     touchEmulation?: boolean;
+    /** 桌面审核操作面板（区域键位映射与屏幕旋转），默认关闭；Mars Runtime 自动启用。
+     * 启用时默认开启 touchEmulation；显式关闭 touchEmulation 时面板一并关闭。 */
+    desktopControls?: boolean;
     /** Visual Inspector 运行时能力；游戏暂停代理默认关闭。 */
     visualInspector?: MiniAppVisualInspectorOptions;
     /** 在父级 bounds 内自适应缩放；默认开启，可传 `false` 关闭或 `{ resizeHandle: true }` 启用手动拖拽缩放 */
@@ -548,6 +551,7 @@ export interface NormalizedMiniAppSimulatorOptions extends Omit<MiniAppSimulator
     timeout: number;
     debug: boolean;
     touchEmulation: boolean;
+    desktopControls: boolean;
     visualInspector: NormalizedMiniAppVisualInspectorOptions;
     stageFit: false | NormalizedMiniAppStageFitOptions;
     jsapi: NormalizedMiniAppJsApiOptions;

package/lib/types/types/renderer.d.ts

@@ -1,3 +1,5 @@
+import type { ScreenRotationDirection } from "../utils/screen-coordinates";
+import type { KeyboardPanelHost } from "../gesture/keyboard-panel";
 import type { InjectionRegistry } from "../injection/registry";
 import type { NotePublishResult, NotePublishViewData } from "../native-ui/note-publish/view-data";
 import type { MiniAppPermissionKind, MiniAppPermissionSheetResult } from "../native-ui/permission-sheet/types";
@@ -99,6 +101,12 @@ export interface RendererAdapterContext {
     debug: boolean;
     /** 是否启用鼠标→触摸事件模拟 */
     touchEmulation?: boolean;
+    /** 显示桌面审核操作面板。 */
+    desktopControls?: boolean;
+    /** Remote Client 承载键位浮窗的内部通道。 */
+    keyboardPanelHost?: KeyboardPanelHost;
+    /** 整台设备 CSS 按指定方向旋转 90 度，保持 guest 逻辑视口尺寸。 */
+    rotateScreen?: (direction: ScreenRotationDirection) => void;
     /** jsapi 注入与 mock 配置 */
     jsapi: NormalizedMiniAppJsApiOptions;
     contentMode: MiniAppContentMode;