@skillbuilder/miniapp-simulator 0.0.0-stage → 0.2.0

package/lib/preload/webview-preload.js

@@ -0,0 +1,37 @@
+(function() {
+  if (!(typeof window > "u")) {
+    var r = "__miniAppWebviewChannelInjected__";
+    if (!window[r]) {
+      window[r] = !0;
+      var n = null;
+      try {
+        n = require("electron").ipcRenderer;
+      } catch {
+        return;
+      }
+      if (n) {
+        var i = "mas:msg";
+        window.addEventListener("message", function(t) {
+          var e = t.data;
+          if (!(!e || typeof e != "object") && typeof e.type == "string")
+            try {
+              n.sendToHost(i, e);
+            } catch {
+            }
+        }), console.info("[mini-app-sdk][guest] webview-preload 通道桥接已注入"), n.on(i, function(t, e) {
+          if (!(!e || typeof e != "object"))
+            try {
+              e.type && console.info("[mini-app-sdk][guest] preload 收到宿主消息", e.type), window.dispatchEvent(
+                new MessageEvent("message", { data: e, source: window })
+              );
+            } catch {
+              try {
+                window.postMessage(e, "*");
+              } catch {
+              }
+            }
+        });
+      }
+    }
+  }
+})();

package/lib/remote-client.js

@@ -0,0 +1,11 @@
+import { R as r, a as O, c as e } from "./client-CO-UjIY3.mjs";
+import { B as s, M as _ } from "./business-line-CMb3ehRn.mjs";
+import { M } from "./index-B5oixYXr.mjs";
+export {
+  s as BusinessLine,
+  _ as MINIAPP_SCREENSHOT_ERROR_CODE,
+  M as MiniAppJsApiErrorCode,
+  r as REMOTE_INSPECTOR_PAUSE_RUNTIME_CAPABILITY,
+  O as REMOTE_SIMULATOR_PROTOCOL_VERSION,
+  e as createRemoteMiniAppSimulator
+};

package/lib/types/business-line.d.ts

@@ -0,0 +1,7 @@
+/** 模拟器支持的业务线；用于远端策略、启动参数和 AI 网关路由。 */
+export declare enum BusinessLine {
+    skillDesignable = "skill-designable",
+    creator = "creator",
+    mars = "mars",
+    dev = "dev"
+}

package/lib/types/capabilities/constants.d.ts

@@ -0,0 +1,29 @@
+import type { CspDirective } from "../types";
+/**
+ * CSP 逐指令默认表。`freeze: true` = 锁死，忽略消费方一切覆盖（安全底线）。
+ *
+ * - 资源类（script/style/img/font/media）：按资源类型配置 `'self'`、`data:`、`blob:`。
+ * - 请求类（connect-src）：仅 `'self'`，消费方按需增加接口域名。
+ * - worker-src：默认关闭，Worker 开关启用时允许同源资源。
+ * - `base-uri`：仅 `'self'`（跨域远程入口的 `<base href>` 由构建时内部补入口 origin）。
+ * - `'none'` 四项：禁插件 / 禁表单外发 / 禁子 frame，锁死。
+ */
+export declare const DEFAULT_CSP_DIRECTIVES: Record<CspDirective, {
+    freeze: boolean;
+    default: Record<string, boolean>;
+}>;
+/** iframe `sandbox` 默认标志表（`true` 的 flag 生效，消费方可传 `false` 关掉）。 */
+export declare const DEFAULT_SANDBOX_FLAGS_MAP: Record<string, boolean>;
+/**
+ * iframe `allow`：委托 Permissions Policy `camera`、`microphone`、`autoplay`（值为 `*`）。
+ * 未列出的能力不向子 frame 主动放权。
+ */
+export declare const DEFAULT_IFRAME_ALLOW_MAP: Record<string, string | string[] | boolean>;
+/**
+ * 子文档 `<meta http-equiv="Permissions-Policy">` 默认表（`feature → allowlist`）。
+ * `false` → `feature=()`（禁用）；`"self"` → `feature=(self)`（仅本文档）。
+ *
+ * 对齐 MiniTool WebView 安全策略 §3.1「禁用（需实现）」+ 纵深防御项。
+ * 「文件选择 / 相册」依赖 sandbox `allow-forms`，不体现在本 header 字段里。
+ */
+export declare const DEFAULT_PERMISSIONS_POLICY_MAP: Record<string, boolean | string | string[]>;

package/lib/types/capabilities/csp-snippet.d.ts

@@ -0,0 +1,34 @@
+import type { CspDirective } from "../types";
+export interface BuildContentSecurityPolicyOptions {
+    /** 当前包会话是否开放 Worker；资源响应层负责下发 Worker CSP。 */
+    workerEnabled?: boolean;
+    /**
+     * 合并后的逐指令 token 表（来自 normalized `security.cspDirectives`）。
+     * 缺省时用内部默认表。
+     */
+    directives?: Record<CspDirective, Record<string, boolean>>;
+    /**
+     * 当前加载的 app URL。其 origin 会被追加进所有非 freeze 指令——
+     * 远程 loadApp / SW 虚拟入口的 `<base href>` 与绝对 URL 子资源解析所需（SW 同源即 'self'）。
+     */
+    appUrl?: string;
+    /**
+     * 额外内部放行源（如 SW 远程代理的远程 origin：其绝对 URL 引用的资源不经 SW、浏览器直连）。
+     * 非消费方 API——追加进所有非 freeze 指令。
+     */
+    extraOrigins?: string[];
+    /** 跨站 iframe 模式下精确放行的宿主 origin；仅用于 frame-ancestors。 */
+    frameAncestors?: string[];
+    /** 传入时 script-src 用 `'nonce-xxx'` 放行注入脚本。 */
+    scriptNonce?: string;
+}
+/**
+ * 构建 CSP（对齐 MiniTool §5.4），SW / webview 模式共用同一套控制。
+ *
+ * 逐指令：freeze 指令（`'none'` 那几个）用默认表锁死；其余取合并后的 token 表，
+ * 并在构建时按 appUrl 做内部增强（追加跨域资源 origin）。
+ */
+export declare function buildDefaultContentSecurityPolicy(options?: BuildContentSecurityPolicyOptions): string;
+export declare function buildContentSecurityPolicyMetaSnippet(options?: BuildContentSecurityPolicyOptions): string;
+/** 生成一次注入用的随机 CSP nonce（16 字节 → base64）。 */
+export declare function generateCspNonce(): string;

package/lib/types/capabilities/launch-options.d.ts

@@ -0,0 +1,7 @@
+/** 容器与 JS SDK 之间的私有启动参数全局名。 */
+export declare const LAUNCH_OPTIONS_GLOBAL_KEY = "$xhs";
+export declare const DEFAULT_USER_DATA_PATH = "";
+/** 模拟器提供的最小启动参数。 */
+export declare function buildSimulatorLaunchOptions(appId?: string, userDataPath?: string, gateways?: Record<string, string>, businessLine?: string): Record<string, unknown>;
+/** 构建在 JS SDK 前执行的启动参数注入脚本。 */
+export declare function buildLaunchOptionsGlobalSource(appId?: string, userDataPath?: string, gateways?: Record<string, string>, businessLine?: string): string;

package/lib/types/capabilities/performance-policy.d.ts

@@ -0,0 +1,5 @@
+/** Default resource limits applied by the simulator runtime. */
+export declare const DEFAULT_MINIAPP_PERFORMANCE_POLICY: {
+    readonly maxHeapUsedBytes: number;
+    readonly heapSampleIntervalMs: 1000;
+};

package/lib/types/capabilities/security-head-snippet.d.ts

@@ -0,0 +1,21 @@
+import { type MiniAppCapability } from "../seal-config";
+import type { CspDirective } from "../types";
+import type { WorkerGuardConfig } from "../worker/adapters/protocol";
+export interface BuildSecurityMetaSnippetOptions {
+    /** 已解析的 Permissions-Policy meta 内容串（来自 normalized security.permissionsPolicy）。 */
+    permissionsPolicy?: string;
+    /** 合并后的 CSP 逐指令 token 表。 */
+    cspDirectives?: Record<CspDirective, Record<string, boolean>>;
+    /** 是否注入 CSP meta，默认 true。SW 模式传 false（CSP 改由响应头下发）。 */
+    csp?: boolean;
+    /** 当前加载的 app URL，用于 CSP 内部增强（跨域 base/资源 origin）。 */
+    appUrl?: string;
+    /** 额外内部放行源（SW 远程代理 origin）。 */
+    extraOrigins?: string[];
+    /** CSP nonce，透传给 CSP meta 的 script-src。 */
+    scriptNonce?: string;
+}
+/** 安全 meta：Permissions-Policy → CSP（`csp:false` 时不出，改走响应头）。 */
+export declare function buildSecurityMetaSnippet(options?: BuildSecurityMetaSnippetOptions): string;
+/** seal 裸源：宿主配置（早于 IIFE）+ 静态 seal 文件 + Worker 生命周期接线。 */
+export declare function buildSealScriptSource(sealAllow?: ReadonlyArray<MiniAppCapability>, workerContext?: WorkerGuardConfig): string;

package/lib/types/capabilities/security.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 安全配置的「token 合并表」解析与序列化工具，以及 zip 路径穿越校验。
+ *
+ * 合并语义统一：`{ ...默认表, ...消费方表 }` → 按各字段值语义序列化成最终串。
+ */
+/**
+ * §6.2：拒绝 zip 路径穿越条目。
+ * @returns 规范化后的相对路径，非法则返回 null
+ */
+export declare function assertSafeZipEntryPath(entryPath: string): string | null;
+/** 取 `Record<token, boolean>` 中值为 `true` 的键（用于 sandbox / CSP 等布尔 token 表）。 */
+export declare function resolveTokenMap(map: Record<string, boolean>): string[];
+/** 解析 iframe `sandbox` 标志表为属性串（取值为 `true` 的 flag 按空格拼接）。 */
+export declare function resolveSandboxFlags(map: Record<string, boolean>): string;
+/**
+ * 序列化 iframe `allow` 表（`feature → allowlist`）为属性串，如 `camera *; microphone 'self'`。
+ * 值为 `false` 的 feature 丢弃；`true` 视为 `*`；string / string[] 为 allowlist。
+ */
+export declare function serializeIframeAllow(map: Record<string, string | string[] | boolean>): string;
+/**
+ * 序列化 Permissions-Policy 表（`feature → allowlist`）为 meta 内容串，如 `geolocation=(), camera=(self)`。
+ * `true` → `feature=*`（放行全部）；`false` → `feature=()`（禁用）；string / string[] → `feature=(self "origin")`。
+ * allowlist 内含 `*` → `feature=*`。
+ */
+export declare function serializePermissionsPolicy(map: Record<string, boolean | string | string[]>): string;

package/lib/types/capabilities/style-snippet.d.ts

@@ -0,0 +1,2 @@
+/** 模拟器固定的子文档基线样式。 */
+export declare function buildStyleSnippet(): string;

package/lib/types/core/controllers/game-playtest.d.ts

@@ -0,0 +1,9 @@
+import type { MiniAppGamePlaytestController, RendererAdapter } from "../../types";
+export interface GamePlaytestControllerDeps {
+    getRenderer(): RendererAdapter | null;
+}
+/**
+ * `simulator.gamePlaytest`：只允许调用版本化游戏桥的固定方法，避免对消费方暴露任意
+ * iframe/window/electron executeJavaScript 能力。
+ */
+export declare function createGamePlaytestController(deps: GamePlaytestControllerDeps): MiniAppGamePlaytestController;

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

@@ -0,0 +1,8 @@
+import type { GestureHostPluginLike, MiniAppGestureController, RendererAdapter } from "../../types";
+export interface GestureControllerDeps {
+    /** 持久化的用户自定义 gesture plugin：跨 reload / renderer 重建保留 */
+    gesturePlugins: Map<string, GestureHostPluginLike>;
+    getRenderer(): RendererAdapter | null;
+}
+/** `simulator.gesture` 控制器：注册 / 卸载手势 plugin 并同步到当前 renderer。 */
+export declare function createGestureController(deps: GestureControllerDeps): MiniAppGestureController;

package/lib/types/core/controllers/host-api.d.ts

@@ -0,0 +1,19 @@
+import type { MiniAppHostApiController, MiniAppHostApiEntry, RendererAdapter } from "../../types";
+export interface HostApiControllerDeps {
+    /**
+     * 宿主能力 map：构造时来自 `options.hostApi`，控制器在其上做增删。
+     * 这个 map **不会**注册到 bridge.handlers；由 bridge 内置 jsapi handler 按需查询。
+     */
+    hostApiMap: Record<string, MiniAppHostApiEntry>;
+    getRenderer(): RendererAdapter | null;
+}
+/**
+ * `simulator.hostApi` 控制器：增删宿主能力 map + 主动 emit 事件。
+ *
+ * 设计要点：
+ *   - hostApi 与 bridge handlers 是两个分离的概念：bridge handler 是 jsapi 实现，
+ *     hostApi 是 jsapi 实现内部可调用的"宿主能力"。
+ *   - 因此 `set/remove/clear/has` 只操作内部 map，不下推到 bridge；
+ *     `emit` 主动推送事件给小应用，直接走 `renderer.bridge`。
+ */
+export declare function createHostApiController(deps: HostApiControllerDeps): MiniAppHostApiController;

package/lib/types/core/controllers/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Controllers 模块 —— `simulator` 上挂载的运行时控制器（hostApi / gesture / notePreview /
+ * permissionSheet）。每个控制器以工厂函数形式注入所需的可变状态访问器，主类只负责编排。
+ */
+export { createHostApiController, type HostApiControllerDeps } from "./host-api";
+export { createGestureController, type GestureControllerDeps } from "./gesture";
+export { createGamePlaytestController, type GamePlaytestControllerDeps } from "./game-playtest";
+export { createInspectorController, type InspectorControllerDeps } from "./inspector";
+export { createPermissionSheetController, type PermissionSheetControllerDeps, } from "./permission-sheet";
+export { createNotePreviewController, type NotePreviewControllerDeps } from "./note-preview";
+export { createWidgetCoverController, type WidgetCoverControllerDeps } from "./widget-cover";

package/lib/types/core/controllers/inspector.d.ts

@@ -0,0 +1,20 @@
+import type { MiniAppInspectorController, MiniAppInspectorSelectionMode, RendererAdapter } from "../../types";
+export interface InspectorControllerDeps {
+    getRenderer(): RendererAdapter | null;
+    /** 读持久化的开启状态（跨 reload / renderer 重建保留） */
+    isEnabled(): boolean;
+    /** 写持久化的开启状态 */
+    setEnabled(value: boolean): void;
+    /** 读写持久化的单选 / 多选模式 */
+    getSelectionMode(): MiniAppInspectorSelectionMode;
+    setSelectionMode(mode: MiniAppInspectorSelectionMode): void;
+    /** 状态变化时向 EventBus emit `inspectorChange` */
+    emitChange(enabled: boolean): void;
+}
+/**
+ * `simulator.inspector` 控制器：开关可视化元素选取模式。
+ *
+ * 状态持久化在主类（`setEnabled`），renderer 重建（load/reload）后由主类自动重应用，
+ * 与 gesture plugin 的持久化语义一致。renderer 未实现选取（webview / 未 mount）时方法为 no-op。
+ */
+export declare function createInspectorController(deps: InspectorControllerDeps): MiniAppInspectorController;

package/lib/types/core/controllers/note-preview.d.ts

@@ -0,0 +1,9 @@
+import type { MiniAppNotePreviewController, NormalizedMiniAppSimulatorOptions } from "../../types";
+export interface NotePreviewControllerDeps {
+    getOptions(): NormalizedMiniAppSimulatorOptions;
+    setOptions(next: NormalizedMiniAppSimulatorOptions): void;
+    /** 把最新 notePreview / rednoteDetail 同步到当前 renderer 壳层 */
+    syncRednote(): void;
+}
+/** `simulator.notePreview` 控制器：运行时增量更新壳层笔记数据（无需 reload）。 */
+export declare function createNotePreviewController(deps: NotePreviewControllerDeps): MiniAppNotePreviewController;

package/lib/types/core/controllers/permission-sheet.d.ts

@@ -0,0 +1,7 @@
+import type { MiniAppPermissionSheetController, RendererAdapter } from "../../types";
+export interface PermissionSheetControllerDeps {
+    getRenderer(): RendererAdapter | null;
+    onResult?(type: string, result: string): void;
+}
+/** `simulator.permissionSheet` 控制器：转发到当前 renderer 的授权弹窗（无渲染器时为 no-op）。 */
+export declare function createPermissionSheetController(deps: PermissionSheetControllerDeps): MiniAppPermissionSheetController;

package/lib/types/core/controllers/widget-cover.d.ts

@@ -0,0 +1,12 @@
+import type { MiniAppWidgetCoverController, NormalizedMiniAppSimulatorOptions } from "../../types";
+export interface WidgetCoverControllerDeps {
+    getOptions(): NormalizedMiniAppSimulatorOptions;
+    setOptions(next: NormalizedMiniAppSimulatorOptions): void;
+    /** 把 widgetCover 同步到当前 renderer 壳层（笔记尾卡 + 个人页卡片） */
+    syncWidgetCover(): void;
+}
+/**
+ * `simulator.widgetCover` 控制器：更新小工具封面（title / cover 部分覆盖），
+ * 笔记轮播尾卡与个人页「作品 → 小工具」卡片两处生效。
+ */
+export declare function createWidgetCoverController(deps: WidgetCoverControllerDeps): MiniAppWidgetCoverController;

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

@@ -0,0 +1,7 @@
+import type { MiniAppSimulatorStatus } from "../types";
+export declare class LifecycleState {
+    private current;
+    get status(): MiniAppSimulatorStatus;
+    transitionTo(next: MiniAppSimulatorStatus): void;
+    assertActive(): void;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * 配置解析与归一化（原 params/{normalize,url-builder}.ts 合并而来）。
+ *
+ *   - parseViewport —— "WxH" 字符串 → viewport
+ *   - normalizeSimulatorOptions —— options → 归一化后内部使用的形态
+ *   - buildMiniAppUrl —— appUrl + options.query → 完整 url
+ */
+import type { MiniAppSecurityOptions, MiniAppSimulatorOptions, MiniAppViewport, NormalizedMiniAppSecurityOptions, NormalizedMiniAppSimulatorOptions } from "../types";
+/**
+ * 深合并 security 补丁：把归一化后的当前值（map 形态）与增量补丁合并成一份
+ * `MiniAppSecurityOptions`，供 `normalizeSimulatorOptions` 再次归一化（幂等）。
+ * cspDirectives 需逐指令浅合并，使配置补丁能正确累积。
+ */
+export declare function mergeSecurity(current: NormalizedMiniAppSecurityOptions, patch: MiniAppSecurityOptions | undefined): MiniAppSecurityOptions;
+/**
+ * normalize 上下文：由 simulator 在创建 shadow host 后注入。
+ * - `container`：渲染器实际挂载点（stage）
+ * - `stageFitBounds`：stageFit 默认可用区域（bounds）
+ */
+export interface NormalizeSimulatorContext {
+    container: HTMLElement;
+    stageFitBounds: HTMLElement;
+}
+/**
+ * 内部配置形态：公开选项 + 仅内部可设置的 `appUrl`（入口由 loadApp / loadZip / loadFiles 写入，不对外暴露）。
+ */
+export type MiniAppSimulatorInternalOptions = MiniAppSimulatorOptions & {
+    appUrl?: string;
+};
+export declare function normalizeSimulatorOptions(options: Omit<MiniAppSimulatorInternalOptions, "mount" | "shadow">, context: NormalizeSimulatorContext): NormalizedMiniAppSimulatorOptions;
+/** 解析 "390x844" 形态的 viewport 字符串；非法返回 undefined。 */
+export declare function parseViewport(value?: string): MiniAppViewport | undefined;
+export declare function buildMiniAppUrl(appUrl: string, query?: Record<string, string | number | boolean | undefined | null>): string;

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

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

package/lib/types/errors.d.ts

@@ -0,0 +1,11 @@
+import type { MiniAppErrorCode } from "./types";
+export declare class MiniAppSimulatorError extends Error {
+    readonly code: MiniAppErrorCode;
+    readonly url?: string;
+    readonly cause?: unknown;
+    constructor(code: MiniAppErrorCode, message: string, options?: {
+        url?: string;
+        cause?: unknown;
+    });
+}
+export declare function toMiniAppSimulatorError(error: unknown, fallbackCode: MiniAppErrorCode): MiniAppSimulatorError;

package/lib/types/event-bus.d.ts

@@ -0,0 +1,15 @@
+import type { MiniAppEventHandler, MiniAppEventMap, MiniAppEventName } from "./types";
+/** `'*'` 通配监听器签名：收到任意事件时被调用，含事件名与原 payload */
+export type MiniAppWildcardHandler = (event: MiniAppEventName, payload: MiniAppEventMap[MiniAppEventName]) => void;
+export declare class EventBus {
+    private readonly listeners;
+    /** 通配监听器集合（订阅所有事件，常用于宿主侧埋点 / tracker） */
+    private readonly wildcardListeners;
+    on<E extends MiniAppEventName>(event: E, handler: MiniAppEventHandler<E>): () => void;
+    on(event: "*", handler: MiniAppWildcardHandler): () => void;
+    once<E extends MiniAppEventName>(event: E, handler: MiniAppEventHandler<E>): () => void;
+    off<E extends MiniAppEventName>(event: E, handler: MiniAppEventHandler<E>): void;
+    off(event: "*", handler: MiniAppWildcardHandler): void;
+    emit<E extends MiniAppEventName>(event: E, payload: MiniAppEventMap[E]): void;
+    clear(): void;
+}

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

@@ -0,0 +1,113 @@
+/**
+ * GestureHostBus — 父窗口侧的事件源 + 调度器。
+ *
+ * 职责：
+ * 1. 创建 overlay div 并挂到 iframe 屏幕区域上方
+ * 2. 监听原始 mouse/wheel/keyboard/blur 事件，转换为 PointerSnapshot
+ * 3. 调度给所有注册的 GestureHostPlugin
+ * 4. 提供共享状态、send / emit / hook 等 plugin 协作机制
+ *
+ * Plugin 通过 `install(ctx)` 订阅事件并往 iframe 发协议消息。
+ */
+import type { GestureDispatchInput, GestureDispatchResult, GestureGuestChannel, GestureHostPlugin, GestureSharedState } from "./types";
+export interface GestureHostBusOptions {
+    /** 内容载体元素（iframe 或 webview）；仅用于坐标换算与聚焦 */
+    element: HTMLElement;
+    /** host↔guest 介质通道（发送/回包/聚焦/cursor），由各 ContentHost 注入 */
+    channel: GestureGuestChannel;
+    /** overlay 挂载位置，一般是载体父容器（手机壳屏幕层或 screenEl） */
+    mountTarget: HTMLElement;
+    /**
+     * 悬停指示（圆点）跟踪区域，默认同 mountTarget。
+     * 半屏详情模式下可设为 contentRoot，使圆点覆盖整台「手机」而非仅 iframe 槽位。
+     */
+    hoverTrackTarget?: HTMLElement;
+    /**
+     * 跨 Shadow DOM 边界的移入监听（一般为 shadow host，light DOM）。
+     * 首次移入模拟器时尚未产生 mousemove，需靠 mouseenter 立即显示圆点。
+     */
+    hoverEnterTarget?: HTMLElement;
+    debug?: boolean;
+}
+export declare class GestureHostBus {
+    private readonly element;
+    private readonly channel;
+    private readonly overlay;
+    private readonly mountTarget;
+    /** 悬停 move/leave 监听区域（可与 mountTarget 不同） */
+    private readonly hoverTrackTarget;
+    /** light DOM 移入边界（shadow host），补 Shadow 穿透场景 */
+    private readonly hoverEnterTarget;
+    private readonly debug;
+    private readonly rawHandlers;
+    private readonly logicHandlers;
+    private readonly plugins;
+    /** 跨 plugin 共享状态 */
+    readonly state: GestureSharedState;
+    private destroyed;
+    /** 当前 mouse 是否正在捕获 mousemove（mousedown 后绑定，mouseup 后解绑） */
+    private capturingWindowMove;
+    /** 业务 plugin 可临时覆盖 cursor，nul 时回到默认 */
+    private overriddenCursor;
+    /** 内置手指指针（圆点）；触摸模拟的核心视觉，独立于事件管线 */
+    private touchCursor;
+    /** guest→host 回包订阅取消句柄（focus-editable 等） */
+    private readonly unsubscribeChannel;
+    constructor(options: GestureHostBusOptions);
+    /**
+     * Sheet / 模态层 / DevTools 元素审查打开时设为 false，避免 overlay 挡住 webview 或拦截 CDP 选点。
+     * 关闭后恢复，不影响手势模拟。
+     */
+    setOverlayInteractionEnabled(enabled: boolean): void;
+    /** 注册一个 plugin；同名 plugin 会被替换 */
+    use(plugin: GestureHostPlugin): void;
+    remove(name: string): boolean;
+    has(name: string): boolean;
+    list(): string[];
+    /**
+     * 回放一段宿主手势。
+     *
+     * 这条路径复用真实鼠标事件使用的 snapshot → plugin → receiver 管线，
+     * 只是把事件源从 DOM overlay 换成受控输入；调用方不需要知道 iframe、overlay
+     * 或坐标缩放细节。
+     */
+    dispatch(input: GestureDispatchInput): Promise<GestureDispatchResult>;
+    /**
+     * 由宿主在 iframe.onload + receiver runtime 注入完成后调用。
+     * 触发 "iframe:ready" 逻辑事件，需要 receiver 就绪后才能 send 的 plugin
+     * （如 `selection-disabler`）可通过 `ctx.hook("iframe:ready", ...)` 监听。
+     */
+    notifyIframeReady(): void;
+    destroy(): void;
+    private makeContext;
+    private subscribeRaw;
+    private subscribeLogic;
+    private emitLogic;
+    private dispatchRaw;
+    private sendToGuest;
+    /**
+     * 把 host 视口坐标转换为 guest CSS 像素空间。
+     * 考虑载体父容器 transform scale，使 guest 内 elementFromPoint / touch.clientX 正确。
+     */
+    private toIframeCoords;
+    private toHostCoords;
+    private syntheticMouseEvent;
+    private syntheticWheelEvent;
+    private modifiersOf;
+    private snapshotOf;
+    /**
+     * 内置手指圆点（TouchCursor）的「模拟器可视区域」判定基准。
+     * 用 light DOM 的 shadow host（铺满 deviceStage、无 transform，rect 最稳），
+     * 回退 hoverTrackTarget。contentRoot 在 stageFit 缩放 + flex 布局下 rect 可能偏移/塌缩。
+     */
+    private get hoverRegion();
+    private onMouseDown;
+    private onMouseMoveDragging;
+    private onMouseUp;
+    private onWheel;
+    private onWindowBlur;
+    /** guest 内表单控件 focus 后，把宿主焦点切到载体，键盘输入才能进小应用 */
+    private onGuestInbound;
+    private bindCapturingWindowMove;
+    private unbindCapturingWindowMove;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Gesture 模块 — PC 模拟器手势插件系统。
+ *
+ * 设计目标：把"宿主鼠标 → iframe 内 touch/click/wheel/contextmenu/dblclick"
+ * 全部抽象为可插拔的 GesturePlugin，host 端 + receiver 端协同。
+ *
+ * 使用：
+ *   ```ts
+ *   const bus = new GestureHostBus({ iframe, mountTarget });
+ *   for (const plugin of createDefaultHostPlugins()) bus.use(plugin);
+ *   // iframe.onload 后注入 receiver runtime
+ *   injectGestureReceiver(iframe);
+ *
+ *   // 业务可注册自定义 plugin
+ *   bus.use({
+ *     name: "shake-emulator",
+ *     install(ctx) {
+ *       ctx.on("down", () => ctx.send({ type: "mini-app:shake" }));
+ *     },
+ *   });
+ *   ```
+ */
+export type { GestureBusMessage, GestureDispatchAction, GestureDispatchInput, GestureDispatchResult, GestureGuestChannel, GestureHostContext, GestureHostPlugin, GestureInboundMessage, GesturePoint, GestureSharedState, ModifierKeys, MultiTouchMode, PointerSnapshot, RawEventName, TapMessage, TouchMessage, WheelMessage, } from "./types";
+export { GestureHostBus } from "./host-bus";
+export { TouchDotManager } from "./touch-dot";
+export { RECEIVER_RUNTIME_SOURCE, injectGestureReceiver, } from "./receiver-runtime";
+export * from "./plugins";

package/lib/types/gesture/plugins/double-tap.d.ts

@@ -0,0 +1,10 @@
+/**
+ * DoubleTapPlugin — 双击手势（300ms 内两次 tap 且位置接近）。
+ *
+ * 依赖 TapPlugin 的 "tap" 逻辑事件，自己不监听原始指针事件。
+ * 触发条件满足时：
+ *   - send `mini-app:dblclick` 给 receiver（派发原生 dblclick）
+ *   - emit "dblclick" 逻辑事件供其他 plugin 使用
+ */
+import type { GestureHostPlugin } from "../types";
+export declare function createDoubleTapPlugin(): GestureHostPlugin;

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

@@ -0,0 +1,27 @@
+/**
+ * 内置的 host-side gesture plugin 工厂集合。
+ *
+ * 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 直接持有，圆点显示不再走事件管线。
+ */
+export { createTouchEmitterPlugin } from "./touch-emitter";
+export { createMultiTouchSwitchPlugin, createPinchPlugin, createRotatePlugin, } from "./multi-touch-switch";
+export { createTapPlugin } from "./tap";
+export { createLongPressPlugin } from "./long-press";
+export { createDoubleTapPlugin } from "./double-tap";
+export { createWheelScrollPlugin } from "./wheel-scroll";
+export { createSelectionDisablerPlugin } from "./selection-disabler";
+export { createMultiTouchHintPlugin } from "./multi-touch-hint";
+import type { GestureHostPlugin } from "../types";
+/** 一次性生成全套内置 plugin（mode-switch 必须在 touch-emitter 之前注册） */
+export declare function createDefaultHostPlugins(): GestureHostPlugin[];

package/lib/types/gesture/plugins/long-press.d.ts

@@ -0,0 +1,13 @@
+/**
+ * LongPressPlugin — 长按手势（500ms 未释放 + 移动 ≤10px）。
+ *
+ * down 时启动定时器，timer 到点时若仍按下且未移动则触发：
+ *   - send `mini-app:longpress` 给 receiver（派发 contextmenu 事件）
+ *   - emit "longpress" 逻辑事件
+ *   - 清空 state.pressStartPoint，使 TapPlugin 在随后的 up 阶段跳过 tap 判定
+ *     （避免"长按后松手"既触发 contextmenu 又触发 click 的双重反应）
+ *
+ * up / leave / move 超过阈值都会取消 timer。
+ */
+import type { GestureHostPlugin } from "../types";
+export declare function createLongPressPlugin(): GestureHostPlugin;

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

@@ -0,0 +1,11 @@
+/**
+ * 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

@@ -0,0 +1,18 @@
+/**
+ * MultiTouchSwitchPlugin / PinchPlugin / RotatePlugin —— 双指模式切换工厂。
+ *
+ * 三者结构一致，区别仅在：检测的修饰键 + 进入时设置的 multiTouchMode。
+ *   - MultiTouchSwitch: shiftKey → "mirror"
+ *   - Pinch:            altKey   → "pinch"
+ *   - Rotate:           ctrlKey  → "rotate"
+ *
+ * 都不直接派发 touch（由 TouchEmitterPlugin 读 state 决定），只控制 state + emit
+ * "multitouch:enter" / "multitouch:leave" 逻辑事件供视觉提示 plugin 使用。
+ */
+import type { GestureHostPlugin } from "../types";
+/** Shift+拖动 = 镜像双指（经典 hammerjs 风格） */
+export declare function createMultiTouchSwitchPlugin(): GestureHostPlugin;
+/** Alt+拖动 = 捏合双指（真实 pinch，副触点直接对称） */
+export declare function createPinchPlugin(): GestureHostPlugin;
+/** Ctrl+拖动 = 旋转双指（副触点关于 base 旋转 180°） */
+export declare function createRotatePlugin(): GestureHostPlugin;

package/lib/types/gesture/plugins/selection-disabler.d.ts

@@ -0,0 +1,11 @@
+/**
+ * SelectionDisablerPlugin — 在 iframe 内禁用文本选中，模拟移动端体感。
+ *
+ * 移动端 long-press 默认是选中文本，但小程序场景一般不希望出现选中蓝条。
+ * 本 plugin 在 iframe ready 时 send `mini-app:selection` { enabled: false }，
+ * receiver 注入 body { user-select: none }。
+ *
+ * 可通过 `simulator.gesture.remove("selection-disabler")` 关闭，恢复文本选中。
+ */
+import type { GestureHostPlugin } from "../types";
+export declare function createSelectionDisablerPlugin(): GestureHostPlugin;