@skillbuilder/miniapp-simulator 0.2.7 → 0.2.9

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-CX13jDtT.mjs";
 import { B as s, M as _ } from "./options-B34ipLmF.mjs";
-import { M } from "./index-CqClPZVv.mjs";
+import { M } from "./index-DwepISqo.mjs";
 export {
   s as BusinessLine,
   _ as MINIAPP_SCREENSHOT_ERROR_CODE,

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

@@ -1,9 +1,249 @@
-import type { MiniAppSimulator as MiniAppSimulatorInterface, MiniAppSimulatorOptions } from "../types";
+import type { KeyboardPanelHost } from "../gesture/keyboard-panel";
+import type { OffloadedResourceSession } from "../offload/resource-session";
+import type { InjectionModule } from "../injection";
+import type { MiniAppContentMode, MiniAppEventHandler, MiniAppEventName, MiniAppFileMap, MiniAppGamePlaytestController, MiniAppGestureController, MiniAppHostApiController, MiniAppInspectorController, MiniAppLoadFilesOptions, MiniAppLoadFilesResult, MiniAppLoadZipOptions, MiniAppLoadZipResult, MiniAppLoadZipSource, MiniAppNotePreviewController, MiniAppPermissionSheetController, MiniAppPhoneFrame, MiniAppRedirectOptions, MiniAppScreenShotResult, MiniAppSimulator as MiniAppSimulatorInterface, MiniAppSimulatorOptions, MiniAppSimulatorRoute, MiniAppSimulatorStatus, MiniAppViewport, MiniAppWidgetCoverController } from "../types";
+declare class MiniAppSimulatorImpl implements MiniAppSimulatorInterface {
+    private readonly runtimeOptions;
+    private readonly lifecycle;
+    private readonly events;
+    /** SDK 在消费方 root 内创建的 shadow 宿主（含 stage / bounds） */
+    private readonly shadowHost;
+    private readonly phoneVibration;
+    /**
+     * 注入清单：security / jsapi / render-done 三个内置模块在 constructor 注册，
+     * 跨 reload 持久存在；后续可由 plugin 追加自定义注入。
+     */
+    private readonly injection;
+    private options;
+    private renderer;
+    /** 只允许最新一次加载继续提交状态；快速切版本时旧解析/挂载会被静默回收。 */
+    private loadGeneration;
+    private loadedUrl;
+    /** 当前 load 的触发来源，供 beforeLoad 事件标记 */
+    private loadSource;
+    /** SW 渲染模式：当前生效的 SW 宿主与已挂载 id（下次加载 / 销毁时 UNMOUNT 回收） */
+    private swHost;
+    private swMountedId;
+    /**
+     * 重算 head 注入所需的入参快照。SW 直供下 head 是 mount 时算好交给 worker 的，
+     * reload 只是重导航虚拟 URL，不会重新走注入装配；运行期新增注入模块（评测探针）
+     * 必须靠这份快照重算并 remount 才能生效。
+     */
+    private swInjectionContext;
+    /**
+     * setHeapLimitOverride 生效前的原值，供恢复用。undefined 表示当前没有覆盖。
+     * 只记一次：评测期间反复改值也只能回到最初的线上限值。
+     */
+    private baseHeapLimit;
+    /** 同步注入与 getLaunchOptions 共用的当前 usr 根路径。 */
+    private userDataPath;
+    /** SW 注册失败后置位：远程 appUrl 后续以真实 URL 直连（跳过 SW 代理） */
+    private serviceWorkerUnavailable;
+    private detachStageFit;
+    /** request / xhsRequest / abortRequest 的独立执行层。 */
+    private readonly requestRuntime;
+    private readonly storageScope;
+    /**
+     * 宿主能力 map：构造时来自 `options.hostApi`，运行时通过 `simulator.hostApi.set` 增删。
+     * **不会**自动注册到 bridge.handlers；只供内置 bridge handler 按需调用，
+     * 即"bridge 实现自己决定是调宿主能力还是 native-ui"。
+     */
+    private readonly hostApiMap;
+    private readonly showJsApiAlert;
+    /** 持久化的用户自定义 gesture plugin：跨 reload / renderer 重建保留 */
+    private readonly gesturePlugins;
+    /** 持久化的选取模式开启状态：跨 reload / renderer 重建后自动重应用 */
+    private inspectorEnabled;
+    /** 可视化选取的单选 / 多选模式：跨 renderer 重建保留 */
+    private inspectorSelectionMode;
+    private readonly tracker;
+    /** Debug 调试面板（仅 options.debug 时实例化）；跨 reload 持久存在 */
+    private devtoolsPanel;
+    /** Debug 面板唤起快捷键卸载函数 */
+    private detachDevtoolsShortcut;
+    /** 当前页面路由（note / minitool / profile） */
+    private currentRoute;
+    /** 小工具收起后回落的活动页（note 笔记页 / profile 个人页） */
+    private activePage;
+    /** JSAPI 模块共用的只读运行态视图；字段访问始终读取最新模拟器状态。 */
+    private get jsapiContext();
+    readonly hostApi: MiniAppHostApiController;
+    readonly gesture: MiniAppGestureController;
+    readonly gamePlaytest: MiniAppGamePlaytestController;
+    readonly inspector: MiniAppInspectorController;
+    readonly notePreview: MiniAppNotePreviewController;
+    readonly widgetCover: MiniAppWidgetCoverController;
+    readonly permissionSheet: MiniAppPermissionSheetController;
+    constructor(options: MiniAppSimulatorOptions, runtimeOptions?: {
+        keyboardPanelHost?: KeyboardPanelHost;
+        requestManagerFrameUrl?: string;
+        gateways?: Record<string, string>;
+        businessLine?: string;
+        trackerContext?: () => Record<string, string | number | undefined>;
+    });
+    /**
+     * 初始化 Debug 调试面板：以 fixed 停靠窗口右侧（挂 document.body，不遮挡模拟器舞台），
+     * 注册 Shift+Cmd/Ctrl+U 唤起快捷键。能力开关仅供内部调试并触发整页 reload。
+     */
+    private initDevtools;
+    /** 从当前归一化选项构造调试面板快照 */
+    private buildDevtoolsSnapshot;
+    /** device 作为渲染容器，bounds 作为 stageFit 默认边界 */
+    private normalizeContext;
+    /** 去掉仅在创建期使用、normalize 不需要的 host / 回调字段 */
+    private stripHostOptions;
+    /** 实例创建时把 option 级回调绑定到对应事件 */
+    private bindLifecycleCallbacks;
+    /**
+     * 合并补丁并重新归一化（深合并 notePreview / security / review，与 updateConfig 一致）。
+     * 入参允许是已归一化形态（来自 this.options）+ 局部覆盖。
+     */
+    private mergeOptions;
+    get status(): MiniAppSimulatorStatus;
+    /**
+     * 尝试调用宿主注册的 getUserInfo handler 获取用户信息，
+     * 用于更新笔记页导航栏与个人页（资料区 / 卡片作者行）的头像和昵称。
+     * 未注册或调用失败时静默保留默认值。
+     */
+    private tryResolveHostUserInfo;
+    private syncRendererRednoteContext;
+    private syncRendererProfileContext;
+    /** 小工具封面：同步到 renderer 壳层（笔记尾卡 + 个人页卡片两处生效） */
+    private syncRendererWidgetCover;
+    /** 更新当前路由；变化时统一发出 routerChange 事件（宿主调用与内部跳转共用） */
+    private setRoute;
+    /** 壳层路由变化：note/profile（头像 / 返回 / 宿主跳转）、minitool（sheet 唤起）、back（sheet 收起回落活动页） */
+    private handleShellRouteChange;
+    getCurrentRoute(): MiniAppSimulatorRoute;
+    redirectTo(route: MiniAppSimulatorRoute, options?: MiniAppRedirectOptions): Promise<void>;
+    load(): Promise<void>;
+    private isCurrentLoad;
+    /** 终止当前 guest，并回收其 renderer 与 SW 挂载。 */
+    private interruptCurrentGuest;
+    private loadCurrent;
+    unload(): void;
+    /**
+     * 执行宿主定制项：函数则直接调用；`{ toast }` 则弹该文案并回成功。
+     */
+    private runHostEntry;
+    private runUnsupportedJsApi;
+    /** 注册模拟器 JSAPI 领域模块；未声明事件仍由 fallback 分发。 */
+    private registerBuiltinBridgeHandlers;
+    reload(): Promise<void>;
+    resize(viewport: MiniAppViewport): void;
+    /** @deprecated 创建实例时传入完整配置；配置变化时销毁并重新创建实例。 */
+    updateConfig(options: Partial<Omit<MiniAppSimulatorOptions, "mount" | "shadow">>): void;
+    setViewport(viewport: MiniAppViewport): void;
+    setZoomFactor(factor: number): void;
+    switchMode(mode: MiniAppContentMode): Promise<void>;
+    switchContentMode(mode: MiniAppContentMode): Promise<void>;
+    switchPhoneFrame(frame: string | MiniAppPhoneFrame | false): Promise<void>;
+    switchDevice(device: string): void;
+    loadApp(appUrl: string, options?: {
+        query?: MiniAppSimulatorOptions["query"];
+    }): Promise<void>;
+    loadZip(source: MiniAppLoadZipSource, options?: MiniAppLoadZipOptions): Promise<MiniAppLoadZipResult>;
+    loadFiles(files: MiniAppFileMap, options?: MiniAppLoadFilesOptions, offloaded?: OffloadedResourceSession): Promise<MiniAppLoadFilesResult>;
+    /**
+     * loadZip / loadFiles 走 `iframe-service-worker`（Web 运行时）：把包文件挂载给
+     * Service Worker 当同源虚拟服务器直供。使用前请把 renderer 设为 `iframe-service-worker`。
+     */
+    private assertServiceWorkerLoader;
+    /** SW 模式前置校验：环境/配置不满足直接抛（宿主据此提示加载失败）。 */
+    private assertServiceWorkerUsable;
+    private toLoadMeta;
+    /** 注册 + 激活 SW（打点注册结果 / 耗时）；注册失败置 serviceWorkerUnavailable，后续跳过 SW。 */
+    private acquireServiceWorkerHost;
+    /** SW 路径：算注入载荷 → 挂载原始文件到 SW → 以同源虚拟 URL 直连（SW 改写 HTML + 下发 CSP）。 */
+    private loadViaServiceWorker;
+    /** 是否对当前远程 appUrl 启用 SW 代理：SW 渲染器 + 配了 scriptUrl + 环境支持 + 未注册失败 + appUrl 为跨域 http(s)。 */
+    private shouldProxyRemoteViaServiceWorker;
+    /** load() 内调用：远程 appUrl 满足条件时挂进 SW 走同源代理；失败经 error 事件暴露并抛出。 */
+    private maybeMountRemoteViaServiceWorker;
+    /** 半屏/全屏壳层收起后再次唤起时，先恢复 SW 注册与内存挂载表，再加载虚拟 URL。 */
+    private restoreServiceWorkerMount;
+    /** 远程 SW 代理：fetch 远程入口 HTML（需开 CORS）→ 注入 → 仅挂入口+remoteBase → appUrl 改写为同源虚拟 URL，子资源由 SW 回源。 */
+    private mountRemoteViaServiceWorker;
+    setTouchEmulation(enabled: boolean): Promise<void>;
+    /** 回收 SW 模式的挂载。 */
+    private unmountServiceWorkerContent;
+    private resolveLoadUrl;
+    private isCurrentServiceWorkerMountUrl;
+    /**
+     * 开关小应用 DevTools。仅 webview 渲染器实现（独立 webContents）；
+     * iframe 渲染器无该能力时为 no-op（DevTools 由宿主整窗负责）。
+     */
+    setDevtools(open: boolean): void;
+    /**
+     * 开关手势 overlay 的 pointer-events（touchEmulation 时生效）。
+     * 宿主嵌入 DevTools 做 Elements 审查时应设为 false，让点击穿透到 guest。
+     */
+    setGestureOverlayInteractionEnabled(enabled: boolean): void;
+    /**
+     * 返回小应用渲染容器的 webContents id（仅 webview 渲染器，dom-ready 后可用，否则 null）。
+     * 不做 lifecycle 断言：宿主可能在 load 完成后立即轮询。
+     */
+    getWebContentsId(): number | null;
+    /**
+     * 注册宿主侧扩展注入模块（评测探针等）。下次 load / reload 生效。
+     *
+     * 注册后会把 security 重新移回末位：seal 锁定内置原型，探针必须在它之前安装，
+     * 否则 hook 目标属性已不可配置，采集静默归零。
+     */
+    registerInjection(module: InjectionModule): void;
+    /** 注销扩展注入模块；下次 load / reload 生效。返回是否命中。 */
+    unregisterInjection(id: string): boolean;
+    /**
+     * 打开评测面板等内容的独立容器：竖直摆放时在设备右侧，旋转时在设备下方。
+     *
+     * 右侧面板在 width 与 maxWidth 之间适度扩展，底部面板占满挂载区宽度。
+     * 设备由 stageFit 在剩余区域内等比适配，桌面操作模式下靠上摆放。
+     */
+    openSidePanel(width: number, maxWidth?: number): HTMLElement;
+    /** 收起侧栏并清空其内容；设备恢复占满整个挂载区。 */
+    closeSidePanel(): void;
+    /** 整块模拟器容器，包含设备、侧栏及容器内留白。 */
+    getInteractionRegions(): readonly HTMLElement[];
+    /**
+     * 临时调整 guest 堆熔断线，供体验评测使用；传 null 恢复建实例时的值。
+     *
+     * 熔断会把整个 iframe 换成 about:blank，注入的探针随 Realm 一起消失，本次采集
+     * 只能作废——而"内存占用大"正是评测最该测出来的事。改值后须调 refreshInjection
+     * 并 reload 才会重新下发 resource-guard 的新阈值。
+     */
+    setHeapLimitOverride(maxHeapUsedBytes: number | false | null): void;
+    /**
+     * 重算 head 注入并就地替换 SW 已挂载实例的注入载荷。
+     *
+     * SW 直供路径下 head 是 mount 时一次性算好交给 worker 的，reload 只重导航虚拟 URL，
+     * 拿到的仍是旧 HTML。运行期通过 registerInjection 新增的模块必须调一次本方法，
+     * 之后的 reload 才会带上新注入。
+     *
+     * 返回 false 表示当前不是 SW 直供状态（无快照），调用方应改走完整 load。
+     */
+    refreshInjection(): Promise<boolean>;
+    capture(): Promise<Blob>;
+    /**
+     * 主动截取小工具运行画面（完整画面）：成功返回 base64 dataURL，失败返回 code + reason（不抛异常）。
+     * 结果同时以 `screenShot` 事件（source: "manual"）对外发出。
+     */
+    screenShot(): Promise<MiniAppScreenShotResult>;
+    destroy(reason?: string): void;
+    on<E extends MiniAppEventName>(event: E, handler: MiniAppEventHandler<E>): () => void;
+    once<E extends MiniAppEventName>(event: E, handler: MiniAppEventHandler<E>): () => void;
+    off<E extends MiniAppEventName>(event: E, handler: MiniAppEventHandler<E>): void;
+    /** 根据渲染器类型创建对应的 Transport；webview 手势 IPC 与 jsapi bridge 共用通道 */
+    private createTransport;
+    private createRenderer;
+    private bindRendererEvents;
+}
 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;
     trackerContext?: () => Record<string, string | number | undefined>;
-}): MiniAppSimulatorInterface;
+}): MiniAppSimulatorImpl;
+export {};

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'） */