@skillbuilder/miniapp-simulator 0.0.0-beta-20261023084421

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

@@ -0,0 +1,844 @@
+import type { MiniAppCapability } from '../seal-config';
+import type { MiniAppMountTarget } from '../host/shadow-host';
+import type { MiniAppPermissionKind, MiniAppPermissionSheetResult } from '../native-ui/permission-sheet/types';
+import type { MiniAppEventHandler, MiniAppEventName } from './events';
+import type { MiniAppInspectorController } from './inspector';
+import type { GestureDispatchInput, GestureDispatchResult } from '../gesture/types';
+export type { GestureDispatchAction, GestureDispatchInput, GestureDispatchResult } from '../gesture/types';
+/**
+ * 配置与运行态类型（原 types.ts 段落 1）。
+ */
+export type MiniAppRendererType = 'webview' | 'iframe-service-worker';
+/**
+ * `renderer: "iframe-service-worker"` 模式的配置。
+ *
+ * 该模式用 Service Worker 把解压后的小工具文件当「同源虚拟服务器」按真实路径
+ * （`/miniapp-simulator/<id>/index.html`）提供，iframe 以真实 URL 直连，相对路径 / ESM / fetch /
+ * `import.meta.url` / Worker 原生可用，无需内联改写。
+ *
+ * 远程 `appUrl`：当 `appUrl` 是**跨域 http(s) 远程链接**时，本模式会自动把它也接入 SW 代理——
+ * 拉取远程入口 HTML 挂载为同源虚拟入口，iframe 加载同源 `/miniapp-simulator/<id>/...`，子资源由
+ * SW 回源到远程。如此浏览器视文档为同源：自然绕过远程站点 `X-Frame-Options` / `frame-ancestors`，
+ * 注入(seal/jsapi/render-done) 与 CSP 照常生效。**前提：远程服务端必须开 CORS**
+ * （返回 `Access-Control-Allow-Origin`）以便读取入口 HTML。
+ *
+ * SW 作用域默认为 `/miniapp-simulator/`。SW 脚本必须由消费方自托管在**同源 http(s)**
+ * 路径（不能跨域 / blob 注册）；远程 Runtime 可通过 `scope` 把所有路径收敛在
+ * `/simulator/*`下。若脚本路径未覆盖该 scope，需在脚本响应头加 `Service-Worker-Allowed`。
+ * 需配置 `scriptUrl` 且运行在支持 SW 的安全上下文；注册 / 挂载失败时通过 `error` 事件暴露。
+ */
+export interface MiniAppServiceWorkerOptions {
+    /**
+     * SW 脚本 URL，相对当前 Runtime 页面解析。
+     * 远程模式下由模拟器服务注入，直接使用与 Runtime 同一 release 的 SW。
+     */
+    scriptUrl: string;
+    /**
+     * SW scope，默认 `/miniapp-simulator/`。必须是同源绝对 pathname，且以 `/` 结尾。
+     * 托管 Runtime 通常传 `/simulator/app/`，使虚拟文件也落在统一网关前缀内。
+     */
+    scope?: string;
+    /**
+     * 由托管 Runtime 注入的外层宿主 origin，仅用于生成虚拟 HTML 的
+     * `frame-ancestors`。普通 SDK 接入无需配置。
+     */
+    frameAncestors?: string[];
+    /** 等待 MOUNT ACK 的超时（ms），超时视为挂载失败经 `error` 事件暴露；默认 5000。 */
+    mountTimeout?: number;
+}
+/**
+ * JS-API 注入模式：
+ * - `auto`（默认）：自动注入；若检测到原 HTML 已自带 jsapi（meta 显式声明或 script 引入）则跳过
+ * - `external`：强制不注入（业务自管 jsapi 引入）
+ * - `off`：完全不注入，连 `<base href>` 都不加（仅用于不依赖 jsapi 的纯 H5 场景）
+ */
+export type JsApiInjectionMode = 'auto' | 'external' | 'off';
+/**
+ * Host API handler 入参：jsapi 调用解析后的协议字段。
+ * 与小工具 jsapi SDK 的 bridge 消息形态保持一致。
+ */
+export interface MiniAppHostApiRequest {
+    /** jsapi event 名（如 `share` / `getUserInfo`） */
+    event: string;
+    /** sdk 传给 invoke 的业务参数（不含 success/fail/complete） */
+    message: Record<string, unknown>;
+    /** callbackId，可用于自定义异步回调时序 */
+    callbackId: string;
+}
+/**
+ * Host API handler 返回的"业务数据"会被 simulator 包装成 `{ code: 0, data }` 回写。
+ * 抛错（同步或 reject）将被视为失败，错误对象可通过 `code` 指定错误码。
+ */
+export type MiniAppHostApiHandler = (request: MiniAppHostApiRequest) => unknown | Promise<unknown>;
+/** 宿主请求适配器接收的统一请求参数，与具体 HTTP 库无关。 */
+export interface MiniAppHostRequestOptions {
+    url: string;
+    method: string;
+    header?: Record<string, string>;
+    data?: unknown;
+    responseType: 'text';
+    enableChunked: boolean;
+    signal: AbortSignal;
+}
+/**
+ * 宿主请求适配器返回的统一响应。宿主负责把 `@xhs/launcher`、XHR 或其他请求库
+ * 的响应转换为该结构；流式响应可把 `data` 设为 ReadableStream。
+ */
+export interface MiniAppHostRequestResponse {
+    statusCode: number;
+    header?: Record<string, string>;
+    data?: unknown;
+}
+/** 宿主注入的通用请求适配器；不包含 taskId 或任何 JS Bridge 事件概念。 */
+export type MiniAppHostRequest = (options: MiniAppHostRequestOptions) => MiniAppHostRequestResponse | Promise<MiniAppHostRequestResponse>;
+/**
+ * 只改内置占位行为的 toast 文案，不接管 api 逻辑。
+ * 调用时弹出该文案并回成功（`{ code: 0 }`）。
+ */
+export interface MiniAppHostApiStub {
+    toast: string;
+}
+/**
+ * `hostApi` 单个 event 的定制项：
+ * - 传函数 → 宿主完整接管该 api 的行为
+ * - 传 `{ toast }` → 沿用内置占位，仅替换提示文案
+ */
+export type MiniAppHostApiEntry = MiniAppHostApiHandler | MiniAppHostRequest | MiniAppHostApiStub;
+export type MiniAppUnsupportedJsApiBehavior = {
+    type: 'toast';
+    message: string;
+} | {
+    type: 'alert';
+    message: string;
+};
+export interface MiniAppJsApiOptions {
+    /**
+     * 整体 jsapi 注入是否启用，默认 `true`。
+     * 关闭后既不会注入 stub，也不会注入 jsapi UMD，iframe 内表现与原始 H5 一致。
+     */
+    enabled?: boolean;
+    /** 注入模式，详见 {@link JsApiInjectionMode}；默认 `auto` */
+    mode?: JsApiInjectionMode;
+    /** jsapi 调用的回调延迟（毫秒），用于模拟端到端往返；默认 60 */
+    defaultDelay?: number;
+    /** 未支持 JSAPI 的统一提示行为；远端 Runtime 可按业务线注入。 */
+    unsupportedBehavior?: MiniAppUnsupportedJsApiBehavior;
+}
+export interface NormalizedMiniAppJsApiOptions {
+    enabled: boolean;
+    mode: JsApiInjectionMode;
+    defaultDelay: number;
+    unsupportedBehavior?: MiniAppUnsupportedJsApiBehavior;
+}
+export type MiniAppSimulatorStatus = 'idle' | 'loading' | 'ready' | 'error' | 'destroyed';
+export interface MiniAppViewport {
+    width: number;
+    height: number;
+}
+export interface MiniAppPhoneFrameScreen {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** 屏幕内容层的圆角半径（px），默认 42 */
+    cornerRadius?: number;
+}
+export interface MiniAppPhoneFrame {
+    id: string;
+    name: string;
+    imageUrl: string;
+    width: number;
+    height: number;
+    screen: MiniAppPhoneFrameScreen;
+}
+/** CSP 指令名。 */
+export type CspDirective = 'default-src' | 'script-src' | 'style-src' | 'img-src' | 'font-src' | 'media-src' | 'connect-src' | 'base-uri' | 'object-src' | 'form-action' | 'frame-src' | 'worker-src' | 'child-src' | 'frame-ancestors';
+/**
+ * 统一安全配置：控制 iframe 内被加载内容的运行时行为（CSP / seal 能力封印 / iframe sandbox / 权限策略）。
+ *
+ * 所有分隔符列表型配置一律用「token 合并表」表示——内部有默认表，消费方传 partial 覆盖：
+ * 增一项 / 删默认项（详见各字段）。取值有效的键按各自分隔符拼接成最终串。
+ */
+export interface MiniAppSecurityOptions {
+    /**
+     * iframe `sandbox` 标志表（`token → boolean`）。
+     * 默认 `allow-scripts/allow-forms/allow-modals/allow-downloads/allow-same-origin`。
+     * `true` 加一个 flag，`false` 删掉某个默认 flag（如需强隔离可传 `{ "allow-same-origin": false }`）。
+     */
+    sandbox?: Record<string, boolean>;
+    /**
+     * iframe `allow`（Permissions Policy 委托）表：`feature → allowlist`。
+     * 默认 `{ camera: "*", microphone: "*", autoplay: "*" }`。
+     * 值：`"*"` 放行全部来源；`"self"` / `["self", "https://cdn.jsdelivr.net"]` 指定来源；`false` 删掉某个默认项。
+     */
+    iframeAllow?: Record<string, string | string[] | boolean>;
+    /**
+     * 子文档 `<meta http-equiv="Permissions-Policy">` 表：`feature → allowlist`。默认全部传感器禁用（`=()`）。
+     * 值：`true` 放行全部（`feature=*`）；`false` 禁用（`feature=()`）；`"self"` / `["self", "https://cdn.jsdelivr.net"]` → `feature=(self "https://cdn.jsdelivr.net")`。
+     */
+    permissionsPolicy?: Record<string, boolean | string | string[]>;
+    /**
+     * CSP 逐指令 token 表覆盖：`{ 'connect-src': { 'https://cdn.jsdelivr.net': true }, 'img-src': { 'data:': false } }`。
+     * `true` 加一个源/关键字，`false` 删掉某个默认 token。`'none'` 那几个指令锁死，忽略此处输入。
+     */
+    cspDirectives?: Partial<Record<CspDirective, Record<string, boolean>>>;
+    /**
+     * seal 能力白名单（值为 `MiniAppCapability` 枚举字符串）。
+     * 不传 → seal 内部使用 DEFAULT_ALLOW；传数组（含空 `[]`）→ 严格按列表放开，未列出的全部封禁。
+     */
+    sealAllow?: ReadonlyArray<MiniAppCapability>;
+}
+/**
+ * 归一化后的 security：各表已与默认表合并（形态仍与 raw 兼容，保证 `mergeOptions` 再归一化幂等）。
+ * 最终串（sandbox 属性 / iframe allow / permissions-policy / CSP）在消费处按需序列化。
+ */
+export interface NormalizedMiniAppSecurityOptions {
+    /** 合并后的 iframe `sandbox` 标志表（取值 `true` 的 flag 序列化为 sandbox 属性） */
+    sandbox: Record<string, boolean>;
+    /** 合并后的 iframe `allow` 表（feature → allowlist） */
+    iframeAllow: Record<string, string | string[] | boolean>;
+    /** 合并后的 Permissions-Policy 表（feature → allowlist） */
+    permissionsPolicy: Record<string, boolean | string | string[]>;
+    /** 合并后的 CSP 逐指令 token 表（全指令；拼串留到 snippet 处，需 appUrl 做内部增强） */
+    cspDirectives: Record<CspDirective, Record<string, boolean>>;
+    /** undefined = 走 seal 内置 DEFAULT_ALLOW；数组 = 显式覆盖 */
+    sealAllow?: ReadonlyArray<MiniAppCapability>;
+}
+export interface MiniAppReviewOptions {
+    collectConsole?: boolean;
+    collectNavigation?: boolean;
+    collectNetwork?: boolean;
+    enableScreenshot?: boolean;
+}
+/**
+ * 小应用运行期资源保护。默认按 renderer 总 JS heap 绝对水位熔断，且不改写浏览器内置 API。
+ * 浏览器只暴露 renderer/V8 isolate 级的 `performance.memory`，不是 iframe 独占内存；同进程
+ * 存在多个模拟器时，采样可能包含其他实例的内存，因此它是兜底熔断，不能替代 Electron
+ * webContents 级的独立内存监控。
+ */
+export interface MiniAppRuntimeLimits {
+    /** renderer 总 JS heap 绝对水位；false 关闭。默认 1 GiB。 */
+    maxHeapUsedBytes?: number | false;
+}
+export interface NormalizedMiniAppRuntimeLimits {
+    maxHeapUsedBytes: number | false;
+    heapSampleIntervalMs: number;
+}
+/**
+ * 将模拟器容器在指定边界元素内按比例缩放并水平居中（保持 layout 尺寸与 transform 后视觉一致，便于触摸坐标换算）。
+ * - 默认开启：无拖拽手柄时 100% 撑满 bounds（`scaleMultiplier: 1` + `capToBounds: true`）
+ * - `true`：使用默认边界为 shadow host 内 bounds
+ * - `false`：不启用自适应缩放
+ */
+export interface MiniAppStageFitOptions {
+    /** 可用区域参照元素，默认 shadow host 内 bounds */
+    bounds?: HTMLElement;
+    padding?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    /** 相对「撑满 bounds」的比例再乘的系数；无拖拽手柄时默认 1，有手柄时默认 0.78 */
+    scaleMultiplier?: number;
+    minScaleMultiplier?: number;
+    maxScaleMultiplier?: number;
+    /** 是否在右上角显示拖拽缩放手柄，默认 false */
+    resizeHandle?: boolean;
+    /** 水平拖动灵敏度（每像素对应的 scaleMultiplier 增量），默认 0.004 */
+    dragSensitivity?: number;
+    /** 手柄相对 bounds 顶部的偏移（px），默认 22 */
+    handleTop?: number;
+    /** 容器相对 bounds 顶部的偏移(px)，默认 18 */
+    contentTop?: number;
+    /** 最终 `transform: scale()` 的下限，默认 0.05 */
+    minScale?: number;
+    /** 最终 `transform: scale()` 的上限，默认不限制 */
+    maxScale?: number;
+    /**
+     * 在 bounds 内水平 + 垂直居中（`translate(-50%, -50%)` + `transform-origin: center`）。
+     * 无拖拽手柄时默认 true；有手柄时默认 false（顶部用 `contentTop`）。
+     */
+    centerInBounds?: boolean;
+    /**
+     * 将显示比例限制在 padding 内「整页装入」的最大比例之内（不超过 `fitScale`），避免拖拽放大溢出视口。
+     * 无拖拽手柄时默认 true；有手柄时默认 false。
+     */
+    capToBounds?: boolean;
+}
+export interface NormalizedMiniAppStageFitOptions {
+    bounds: HTMLElement;
+    padding: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    scaleMultiplier: number;
+    minScaleMultiplier: number;
+    maxScaleMultiplier: number;
+    resizeHandle: boolean;
+    dragSensitivity: number;
+    handleTop: number;
+    contentTop: number;
+    minScale: number;
+    maxScale: number;
+    centerInBounds: boolean;
+    capToBounds: boolean;
+}
+/** 模拟器内容模式：`fullscreen` 全屏（右侧滑入、返回键关闭） / `half` 半屏（下滑收起、上滑展开） */
+export type MiniAppContentMode = 'fullscreen' | 'half';
+/** 外壳模式：`rednote` 小红书笔记详情壳（默认） / `none` 无壳纯面板 */
+export type MiniAppShellMode = 'rednote' | 'none';
+/**
+ * 模拟器页面路由：
+ * - `note` 笔记页
+ * - `minitool` 小工具页（运行内容，默认全屏）
+ * - `profile` 个人页
+ */
+export type MiniAppSimulatorRoute = 'note' | 'minitool' | 'profile';
+/** `redirectTo` 可选参数 */
+export interface MiniAppRedirectOptions {
+    /** 仅 `route === "minitool"` 时生效：half 半屏 / full 全屏，默认 `full` */
+    sheetMode?: 'half' | 'full';
+}
+/** 小工具信息：笔记轮播尾卡 + 个人页「作品 → 小工具」卡片共用 */
+export interface XhsWidgetCoverData {
+    /** 标题；不传默认「小工具模拟器」 */
+    title?: string;
+    /** 封面图 url / dataURL；不传用 SDK 自动截图结果（内部按 3:4 裁剪展示） */
+    cover?: string;
+}
+/** `simulator.widgetCover` 控制器：运行时更新小工具封面（笔记尾卡 + 个人页卡片两处生效，无需 reload） */
+export interface MiniAppWidgetCoverController {
+    /** 部分字段更新（title / cover 单独覆盖） */
+    update(data: Partial<XhsWidgetCoverData>): void;
+}
+/**
+ * 个人页用户信息（内部数据，非对外 API）：由 hostApi `getUserInfo` 自动填充，
+ * 驱动个人页卡片作者行的头像 / 昵称。
+ */
+export interface XhsProfilePreviewData {
+    user?: XhsNotePreviewUser;
+}
+/** `screenShot` 失败码：not-loaded 未加载 / render-failed 渲染异常 / timeout 截图超时 / unsupported 环境不支持 */
+export declare const MINIAPP_SCREENSHOT_ERROR_CODE: {
+    /** 小工具尚未加载（含占位态 / 不在小工具页） */
+    readonly notLoaded: "not-loaded";
+    /** 页面渲染异常，截图内容不可用 */
+    readonly renderFailed: "render-failed";
+    /** 截图超时 */
+    readonly timeout: "timeout";
+    /** 当前环境不支持截图 */
+    readonly unsupported: "unsupported";
+};
+export type MiniAppScreenShotErrorCode = (typeof MINIAPP_SCREENSHOT_ERROR_CODE)[keyof typeof MINIAPP_SCREENSHOT_ERROR_CODE];
+/** `screenShot` 结果：成功携带 base64 dataURL，失败携带 code + reason */
+export type MiniAppScreenShotResult = {
+    success: true;
+    /** 完整 dataURL（`data:image/png;base64,xxx`），可直接用于 `<img>` 或上传 */
+    base64: string;
+    width: number;
+    height: number;
+    /** auto = 部署成功后自动截图；manual = 宿主主动调用 `screenShot()` */
+    source: 'auto' | 'manual';
+} | {
+    success: false;
+    code: MiniAppScreenShotErrorCode;
+    /** 人类可读的失败原因 */
+    reason: string;
+};
+export interface XhsNotePreviewUser {
+    avatar: string;
+    nickname: string;
+}
+export interface XhsNotePreviewImage {
+    url: string;
+    ratio?: number;
+}
+/** 笔记正文里的小工具入口卡片（点击「使用」唤起半屏预览） */
+export interface XhsNoteAppCardData {
+    /** 卡片标题（小工具名称），默认「小工具模拟器」 */
+    name?: string;
+    /** 卡片副标题/描述 */
+    desc?: string;
+    /** 卡片左侧图标 URL；不传则用默认渐变占位 */
+    icon?: string;
+}
+export interface XhsNotePreviewData {
+    user: XhsNotePreviewUser;
+    title?: string;
+    descHtml?: string;
+    images?: XhsNotePreviewImage[];
+    cover?: XhsNotePreviewImage;
+    /** 聚焦小工具时展示的首页截图；不影响 1/2、2/2 笔记图片页。 */
+    widgetCover?: XhsNotePreviewImage;
+    noteType?: 'image' | 'video';
+    /** 笔记内的小工具入口卡片信息 */
+    appCard?: XhsNoteAppCardData;
+}
+export interface RednoteDetailSheetOptions {
+    /** 半屏占屏幕内容区高度比例，默认 0.85 */
+    heightRatio?: number;
+    /** 无 appUrl 时的占位文案 */
+    placeholderText?: string;
+}
+export interface NormalizedRednoteDetailSheetOptions {
+    heightRatio: number;
+    placeholderText: string;
+}
+export interface MiniAppNotePreviewController {
+    /** 更新壳层笔记数据（部分字段，未传字段保留当前值并与 SDK 默认兜底 merge） */
+    update(data: Partial<XhsNotePreviewData>): void;
+    /** 仅更新顶栏用户头像与昵称（运行时切换，无需 reload） */
+    updateUser(user: Partial<XhsNotePreviewUser>): void;
+    /** 仅更新笔记内小工具入口卡片（名称 / 描述 / 图标，运行时切换，无需 reload） */
+    updateAppCard(appCard: Partial<XhsNoteAppCardData>): void;
+}
+/** Visual Inspector 的可选运行时能力。默认只注入轻量场景桥，不改写页面调度器。 */
+export interface MiniAppVisualInspectorOptions {
+    /**
+     * 是否注入游戏暂停运行时。开启后会从业务脚本执行前代理 RAF / timer，供圈选时冻结场景。
+     * 仅应由明确的 2D / 3D 游戏预览开启；普通小工具保持 false，避免改变调度行为。
+     */
+    pauseRuntime?: boolean;
+}
+export interface NormalizedMiniAppVisualInspectorOptions {
+    pauseRuntime: boolean;
+}
+/**
+ * 加载链路生命周期回调（option 级），等价于对应 `simulator.on(eventName, handler)`，
+ * 在实例创建时即绑定，便于在首帧加载前注册。
+ */
+export interface MiniAppLifecycleCallbacks {
+    /** 渲染容器初始化完成（renderer mount 之后、加载之前） */
+    onReady?: MiniAppEventHandler<'ready'>;
+    /** 即将开始加载（renderer.load 之前），可用于 .zip/url 加载前埋点 */
+    onBeforeLoad?: MiniAppEventHandler<'beforeLoad'>;
+    /** URL 加载完成（iframe/webview onload） */
+    onLoad?: MiniAppEventHandler<'load'>;
+    /** 小应用首屏渲染完毕（子文档首帧绘制后回报） */
+    onRenderDone?: MiniAppEventHandler<'renderDone'>;
+    onError?: MiniAppEventHandler<'error'>;
+    onNavigation?: MiniAppEventHandler<'navigation'>;
+    onConsole?: MiniAppEventHandler<'console'>;
+    onNetwork?: MiniAppEventHandler<'network'>;
+    onDestroy?: MiniAppEventHandler<'destroy'>;
+}
+export interface MiniAppSimulatorOptions extends MiniAppLifecycleCallbacks {
+    /** 页面切换回调（宿主调用 `redirectTo` 与模拟器内部跳转均触发） */
+    onRouterChange?: MiniAppEventHandler<'routerChange'>;
+    /** 截图结果回调（auto 自动截图与 manual 主动截图均触发） */
+    onScreenShot?: MiniAppEventHandler<'screenShot'>;
+    /**
+     * 挂载目标：CSS 选择器或 HTMLElement。SDK 会在其内部创建自己的宿主元素，
+     * 并默认以 Shadow DOM 隔离样式，仅渲染"干净的设备舞台"（手机本体）。
+     */
+    mount: MiniAppMountTarget;
+    /** 是否启用 Shadow DOM 样式隔离，默认 `true` */
+    shadow?: boolean;
+    /**
+     * 可选的稳定 app 身份（如 projectId / miniappId / appId），作为运行期文件系统
+     * （writeTempFile 等）的持久化存储桶 key。**传入即持久化到 IndexedDB、跨会话可读**；
+     * 不传则以随机 mountId 为桶、仅当前会话内存有效。接入方一行 opt-in，无需层层下传。
+     */
+    appId?: string;
+    /** 内容展示模式，默认 `fullscreen` */
+    contentMode?: MiniAppContentMode;
+    /**
+     * 外壳模式，默认 `rednote`（小红书笔记详情壳：状态栏 / 顶栏 / home indicator / 设备边框）。
+     * `none` 为无壳纯面板：不挂 rednote 壳层、不加设备边框圆角，内容直接铺满挂载区，
+     * 与「把 HTML 直接内嵌到 iframe」的裸预览效果一致。仅 iframe 渲染器生效。
+     */
+    shell?: MiniAppShellMode;
+    /** Feed / Detail 壳层笔记数据 */
+    notePreview?: XhsNotePreviewData;
+    /** 小工具封面初始数据（笔记尾卡 + 个人页卡片两处生效） */
+    widgetCover?: XhsWidgetCoverData;
+    /** half / fullscreen 壳层共用的半屏配置 */
+    rednoteDetail?: RednoteDetailSheetOptions;
+    renderer?: MiniAppRendererType;
+    /** `renderer: "iframe-service-worker"` 模式的配置（消费方自托管 SW 脚本）。 */
+    serviceWorker?: MiniAppServiceWorkerOptions;
+    viewport?: MiniAppViewport;
+    device?: 'iphone-15-pro' | 'iphone-15-pro-max' | 'ipad-pro' | 'pc' | string;
+    /** 贴图手机外壳 id 或配置；默认 `false`（无贴图壳，保留标准深色圆角边框） */
+    phoneFrame?: string | MiniAppPhoneFrame | false;
+    query?: Record<string, string | number | boolean | undefined | null>;
+    review?: MiniAppReviewOptions;
+    /** 失控业务的运行期熔断配置。 */
+    runtimeLimits?: MiniAppRuntimeLimits;
+    timeout?: number;
+    /**
+     * 开启内置调试模式（默认 `false`，由模拟器开发者控制）。
+     * 开启后：
+     * - 各子系统输出 `console` 调试日志；
+     * - 支持 `Shift + Cmd/Ctrl + U` 快捷键在模拟器内唤起调试面板，
+     *   覆盖「能力管控（动态启停封印能力并重载）」与「运行日志 / 关键事件」。
+     */
+    debug?: boolean;
+    /** 开启鼠标→触摸事件模拟，使桌面端鼠标操作还原真机 touch 行为（显示小手光标与触点圆点） */
+    touchEmulation?: boolean;
+    /** Visual Inspector 运行时能力；游戏暂停代理默认关闭。 */
+    visualInspector?: MiniAppVisualInspectorOptions;
+    /** 在父级 bounds 内自适应缩放；默认开启，可传 `false` 关闭或 `{ resizeHandle: true }` 启用手动拖拽缩放 */
+    stageFit?: boolean | MiniAppStageFitOptions;
+    /**
+     * 内置 jsapi 注入与 PC mock 行为。默认开启（auto 模式 + toast）。
+     * 传 `false` 等同于 `{ enabled: false }`。
+     */
+    jsapi?: boolean | MiniAppJsApiOptions;
+    /**
+     * 统一安全配置：控制 iframe 内被加载内容的运行时行为（CSP / seal 封印 / iframe sandbox / 权限策略）。
+     * 各项均有默认、可逐项覆盖（token 合并表语义，见 {@link MiniAppSecurityOptions}）。
+     */
+    security?: MiniAppSecurityOptions;
+    /**
+     * 宿主能力 map —— 注入到 jsapi bridge。
+     *
+     * key 为能力名，value 为 {@link MiniAppHostApiEntry}：
+     * 传函数则宿主完整接管该 api；传 `{ toast }` 则沿用内置占位、仅替换提示文案。
+     * 等价于实例化后调用 `simulator.hostApi.set(event, entry)`。
+     *
+     * 优先级：某 event 注册了 entry → 用宿主定制，覆盖模拟器内置行为
+     * （如 `postNote` 默认「请前往真机调试」占位）；未注册的 event 走模拟器内置能力。
+     * 按 event 逐个定制。私有 `xhsRequest` 会使用 `hostApi.request` 注入的统一
+     * 请求适配器；宿主只需适配所用 HTTP 库，无需理解 taskId 或 Bridge 事件。
+     */
+    hostApi?: Record<string, MiniAppHostApiEntry>;
+    /**
+     * 全局事件订阅（埋点 / tracker）。等价于 `simulator.on('*', handler)`。
+     * 收到任意 simulator 事件（load/renderDone/error/navigation/...）都会触发。
+     */
+    onEvent?: (event: MiniAppEventName, payload: unknown) => void;
+    /**
+     * 模拟器生命周期 Tracker。监听启动/加载/渲染/销毁等流程事件并上报。
+     * - `{ business_line }` → 内置默认上报（直接 POST 自定义打点到 APM 端点，可用 `endpoint` 覆盖）
+     * - 不传 / `false` → 不启用
+     *
+     * `business_line` 必填，用于区分使用模拟器的平台（`creator` / `audit`）；
+     * 如需上报用户 ID，可提供 `getUserInfo`。
+     */
+    tracker?: MiniAppTrackerInput;
+}
+export interface NormalizedMiniAppSimulatorOptions extends Omit<MiniAppSimulatorOptions, 'mount' | 'shadow' | 'stageFit' | 'jsapi' | 'rednoteDetail' | 'security' | 'inject' | 'runtimeLimits' | 'visualInspector' | keyof MiniAppLifecycleCallbacks> {
+    /** 渲染器实际挂载点（shadow host 内的 stage 元素） */
+    container: HTMLElement;
+    appUrl: string;
+    contentMode: MiniAppContentMode;
+    shell: MiniAppShellMode;
+    notePreview: XhsNotePreviewData;
+    profilePreview: XhsProfilePreviewData;
+    widgetCover: XhsWidgetCoverData;
+    rednoteDetail: NormalizedRednoteDetailSheetOptions;
+    renderer: MiniAppRendererType;
+    viewport: MiniAppViewport;
+    phoneFrame?: MiniAppPhoneFrame;
+    query: Record<string, string | number | boolean | undefined | null>;
+    review: Required<MiniAppReviewOptions>;
+    runtimeLimits: NormalizedMiniAppRuntimeLimits;
+    timeout: number;
+    debug: boolean;
+    touchEmulation: boolean;
+    visualInspector: NormalizedMiniAppVisualInspectorOptions;
+    stageFit: false | NormalizedMiniAppStageFitOptions;
+    jsapi: NormalizedMiniAppJsApiOptions;
+    security: NormalizedMiniAppSecurityOptions;
+}
+/**
+ * 运行时 gesture 控制器，挂在 `simulator.gesture` 上。
+ *
+ * 当前 renderer 已挂载手势总线且 `touchEmulation: true` 时生效；其他场景 dispatch 会明确失败，
+ * plugin 管理方法仍按 renderer 能力生效。
+ * 业务可注册自定义 plugin 扩展宿主侧手势能力（例如"摇一摇"模拟、自定义双指轨迹等）。
+ * Plugin 接口见 `src/gesture/types` 中的 `GestureHostPlugin`（包内模块，非主入口导出）。
+ */
+export interface MiniAppGestureController {
+    /** 回放一段通用手势；坐标使用小应用 guest CSS 像素，由当前 renderer 负责换算。 */
+    dispatch(input: GestureDispatchInput): Promise<GestureDispatchResult>;
+    /** 注册或替换一个 plugin（按 name 去重；同名 plugin 会先 uninstall 再 install） */
+    use(plugin: GestureHostPluginLike): void;
+    /** 卸载一个 plugin，返回是否命中 */
+    remove(name: string): boolean;
+    /** 当前是否安装了某个 plugin */
+    has(name: string): boolean;
+    /** 当前所有 plugin 名称（顺序与注册顺序一致） */
+    list(): string[];
+}
+/** 受控的 `window.__GAME_TEST__` 调用面；不接受任意脚本字符串。 */
+export interface MiniAppGamePlaytestController {
+    manifest(): Promise<unknown>;
+    snapshot(): Promise<unknown>;
+    act(action: Record<string, unknown>): Promise<unknown>;
+    step(ms: number): Promise<unknown>;
+    reset(seed?: number): Promise<unknown>;
+    /** 当前预览是否安装了 version=1 的游戏测试桥。 */
+    isAvailable(): Promise<boolean>;
+}
+/**
+ * Plugin 接口的最小骨架；详细定义见 `GestureHostPlugin`。
+ * 这里用结构化类型避免 types 文件直接依赖 gesture 模块。
+ */
+export interface GestureHostPluginLike {
+    readonly name: string;
+    install(ctx: unknown): void;
+    uninstall?(): void;
+}
+/** 宿主权限授权 Bottom Sheet（仅 iframe 渲染器） */
+export interface MiniAppPermissionSheetController {
+    /**
+     * 展示授权弹窗。
+     * @param kinds 要展示的权限项；省略则使用 V1 入口写死的全量列表
+     */
+    show(kinds?: MiniAppPermissionKind[]): Promise<MiniAppPermissionSheetResult>;
+    hide(): void;
+}
+/**
+ * 运行时 host api 控制器，挂在 `simulator.hostApi` 上。
+ *
+ * 在 simulator load 之前/之后均可调用，下一次回调时生效。
+ * 与构造时的 `options.hostApi` 共用同一个 handler 池：构造时是声明式 map，
+ * 这里是命令式增删。
+ */
+export interface MiniAppHostApiController {
+    /** 注册或覆盖某个 event 的定制项（函数 or `{ toast }`） */
+    set(event: string, entry: MiniAppHostApiEntry): void;
+    /** 批量注册（与 `options.hostApi` 同语义） */
+    registerAll(map: Record<string, MiniAppHostApiEntry>): void;
+    /** 移除某个 event 的定制项，下次调用回落到模拟器内置能力 */
+    remove(event: string): void;
+    /** 清空所有定制项 */
+    clear(): void;
+    /** 是否已注册定制项 */
+    has(event: string): boolean;
+    /**
+     * 主动向小应用推送事件，触发 jsapi 的 `subscribe(method, ...)` 监听。
+     * 等价于真机宿主调用 `window.XHS_SDK_EVENTS_CALLBACKS({type:'events', method, payload})`。
+     */
+    emit(method: string, payload?: unknown): void;
+}
+/** `simulator.loadZip()` 可接收的二进制来源。 */
+export type MiniAppLoadZipSource = Blob | File | ArrayBuffer | Uint8Array;
+/** `simulator.loadZip()` 可选注入的 JSZip 兼容对象（仅需静态 `loadAsync`）。 */
+export interface MiniAppLoadZipJsZip {
+    loadAsync(input: Blob | ArrayBuffer | Uint8Array): Promise<unknown>;
+}
+/** `simulator.loadZip()` 返回的包内文件条目。 */
+export interface MiniAppLoadZipFileEntry {
+    path: string;
+    size: number;
+}
+/** `simulator.loadZip()` 返回结果（包元信息）。 */
+export interface MiniAppLoadZipResult {
+    entry: string;
+    files: MiniAppLoadZipFileEntry[];
+}
+/** loadZip/loadFiles 的包体积准入上限。 */
+export interface MiniAppPackageLimits {
+    /** ZIP 压缩包最大字节数，默认 50 MiB。仅 loadZip 生效。 */
+    maxZipBytes: number;
+    /** 任一文件最大字节数，默认 15 MiB。 */
+    maxSingleFileBytes: number;
+    /** JS/TS 脚本单文件最大字节数，默认 15 MiB。 */
+    maxScriptBytes: number;
+}
+/** `simulator.loadZip()` 选项。 */
+export interface MiniAppLoadZipOptions {
+    /**
+     * JSZip 兼容对象（含静态 `loadAsync`）。
+     * 不传则回退到全局 `window.JSZip`（CDN / UMD 注入）；仍缺失时抛错。
+     */
+    jszip?: MiniAppLoadZipJsZip;
+    /** 入口 HTML 文件名，默认 `index.html`。 */
+    entry?: string;
+    /** 追加 / 覆盖到加载 URL 的 query（与现有 query 合并）。 */
+    query?: MiniAppSimulatorOptions['query'];
+    /** 解包准入上限；传 false 关闭，partial 覆盖默认保护值。 */
+    limits?: Partial<MiniAppPackageLimits> | false;
+}
+/**
+ * `simulator.loadFiles()` 单个文件内容。
+ * - 文本资源（html / css / js / json）：传 `string`
+ * - 二进制资源（图片 / 字体）：传 `ArrayBuffer` / `Uint8Array`（或已编码的 `data:` URI 字符串）
+ */
+export type MiniAppFileContent = string | ArrayBuffer | Uint8Array;
+/**
+ * `simulator.loadFiles()` 入参：相对路径 → 文件内容 的映射。
+ * 适用于「AI 出码目录产物」等无 zip 打包场景：宿主（Node / Electron）读好目录后传入，
+ * SDK 复用与 loadZip 相同的路径 → 字节文件表，交 Service Worker 直供，自身不做文件系统 IO。
+ *
+ * @example
+ * await simulator.loadFiles({
+ *   "index.html": htmlText,
+ *   "style.css": cssText,
+ *   "logo.png": pngBytes, // Uint8Array
+ * });
+ */
+export type MiniAppFileMap = Record<string, MiniAppFileContent>;
+/** `simulator.loadFiles()` 选项。 */
+export interface MiniAppLoadFilesOptions {
+    /** 入口 HTML 文件名，默认 `index.html`。 */
+    entry?: string;
+    /** 追加 / 覆盖到加载 URL 的 query（与现有 query 合并）。 */
+    query?: MiniAppSimulatorOptions['query'];
+    /** 文件表准入上限；传 false 关闭，partial 覆盖默认保护值。 */
+    limits?: Partial<MiniAppPackageLimits> | false;
+}
+/** `simulator.loadFiles()` 返回结果（文件清单），结构与 loadZip 对齐。 */
+export interface MiniAppLoadFilesResult {
+    entry: string;
+    files: MiniAppLoadZipFileEntry[];
+}
+export interface MiniAppSimulator {
+    readonly status: MiniAppSimulatorStatus;
+    /**
+     * 运行时 host api 控制器；仅当 jsapi.enabled 时生效，关闭时所有调用为 no-op。
+     * 与构造时传入的 `options.hostApi` 共用同一个 handler 池。
+     */
+    readonly hostApi: MiniAppHostApiController;
+    /** 运行时 gesture 控制器；不支持手势回放的 renderer 调用 dispatch 会明确失败 */
+    readonly gesture: MiniAppGestureController;
+    /** `?playtest=1` 游戏预览的受控语义操作器；iframe/webview 统一实现。 */
+    readonly gamePlaytest: MiniAppGamePlaytestController;
+    /**
+     * 可视化元素选取控制器；仅 iframe + 同源可访问时生效，其余场景为 no-op。
+     * 配合 `on('elementSelected' | 'elementHovered', ...)` 消费选区结果。
+     */
+    readonly inspector: MiniAppInspectorController;
+    /** 更新 Feed / Detail 壳层笔记数据（无需 reload） */
+    readonly notePreview: MiniAppNotePreviewController;
+    /** 更新小工具封面：笔记尾卡 + 个人页卡片两处生效（无需 reload） */
+    readonly widgetCover: MiniAppWidgetCoverController;
+    /** 权限授权 Bottom Sheet（iframe 渲染器挂载） */
+    readonly permissionSheet: MiniAppPermissionSheetController;
+    load(): Promise<void>;
+    /** 立即终止当前 guest 并回收 iframe / WebGL / SW 挂载；实例本身可继续 load。 */
+    unload(): void;
+    /**
+     * 跳转页面（note 笔记页 / minitool 小工具页 / profile 个人页）。
+     * `minitool` 默认全屏打开，可用 `options.sheetMode: "half"` 指定半屏。
+     * 跳转同样会触发 `routerChange` 事件（宿主可据此去重回声）。
+     */
+    redirectTo(route: MiniAppSimulatorRoute, options?: MiniAppRedirectOptions): Promise<void>;
+    /** 当前页面路由 */
+    getCurrentRoute(): MiniAppSimulatorRoute;
+    /**
+     * 主动截取小工具运行画面（完整画面）：成功返回 base64 dataURL，失败返回 code + reason。
+     * 结果同时以 `screenShot` 事件（source: "manual"）对外发出。
+     */
+    screenShot(): Promise<MiniAppScreenShotResult>;
+    reload(): Promise<void>;
+    resize(viewport: MiniAppViewport): void;
+    /** 设置逻辑视口尺寸（`resize` 的语义化别名） */
+    setViewport(viewport: MiniAppViewport): void;
+    /**
+     * 设置渲染缩放系数（1 = 100%）。仅 webview 渲染器生效（走 guest `webContents.setZoomFactor`），
+     * iframe 渲染器为 no-op（其缩放由 stageFit 负责）。可在 load 前调用，dom-ready 后自动补应用。
+     */
+    setZoomFactor(factor: number): void;
+    /** 切换内容模式：fullscreen / half（会重新加载） */
+    switchContentMode(mode: MiniAppContentMode): Promise<void>;
+    /** `switchContentMode` 的简写别名 */
+    switchMode(mode: MiniAppContentMode): Promise<void>;
+    /** 切换 / 关闭手机外壳（会重建渲染器并重新加载） */
+    switchPhoneFrame(frame: string | MiniAppPhoneFrame | false): Promise<void>;
+    /** 切换设备预设（联动逻辑视口；仅 resize，不重载） */
+    switchDevice(device: string): void;
+    /** 加载新的小工具入口 URL（可附带 query，会重新加载） */
+    loadApp(appUrl: string, options?: {
+        query?: MiniAppSimulatorOptions['query'];
+    }): Promise<void>;
+    /**
+     * 自动加载 .zip 小工具包：内部解压为原始文件表 → 挂载给 Service Worker 当同源虚拟服务器直供
+     * → iframe 直连虚拟 URL（会重新加载）。需 renderer: "iframe-service-worker"。
+     * 返回包元信息（文件清单），便于业务侧展示。
+     */
+    loadZip(source: MiniAppLoadZipSource, options?: MiniAppLoadZipOptions): Promise<MiniAppLoadZipResult>;
+    /**
+     * 加载「目录文件表」：宿主读好目录后传入「相对路径 → 内容」映射，
+     * 内部复用 loadZip 的文件表挂载链路交 Service Worker 直供（会重新加载）。
+     * 适用于 AI 出码目录产物等无 zip 打包场景。返回文件清单。
+     */
+    loadFiles(files: MiniAppFileMap, options?: MiniAppLoadFilesOptions): Promise<MiniAppLoadFilesResult>;
+    /** 开关鼠标→触摸事件模拟（会重新加载渲染器） */
+    setTouchEmulation(enabled: boolean): Promise<void>;
+    /**
+     * @deprecated 创建实例时传入完整配置；配置变化时销毁并重新创建实例。
+     */
+    updateConfig(options: Partial<Omit<MiniAppSimulatorOptions, 'mount' | 'shadow'>>): void;
+    capture(): Promise<Blob>;
+    /**
+     * 开关小应用 DevTools。
+     * 仅 webview 渲染器生效（弹出小应用专属 Chrome DevTools）；
+     * iframe 渲染器为 no-op（DevTools 由宿主整窗负责）。
+     */
+    setDevtools(open: boolean): void;
+    /**
+     * 开关手势 overlay 的 pointer-events。
+     * 宿主嵌入 DevTools 做 Elements 审查时设为 false，让点击穿透到 guest webview/iframe。
+     */
+    setGestureOverlayInteractionEnabled(enabled: boolean): void;
+    /**
+     * 返回小应用渲染容器的 webContents id（仅 webview 渲染器，dom-ready 后可用，否则 null）。
+     * 宿主可据此在主进程把真 Chrome DevTools 嵌入自定义面板（setDevToolsWebContents）。
+     */
+    getWebContentsId(): number | null;
+    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;
+}
+/**
+ * 框架 Adapter 选项：去掉 mount（由 adapter 提供 DOM ref），其余配置与生命周期回调
+ * 直接复用 `MiniAppSimulatorOptions`（回调已内置于核心选项中）。
+ */
+export type MiniAppFrameworkAdapterOptions = Omit<MiniAppSimulatorOptions, 'mount'>;
+/**
+ * Tracker 上报事件结构。
+ * name 为事件名（如 `simulator_load`），payload 为事件负载。
+ */
+export interface MiniAppTrackerEvent {
+    name: string;
+    payload: Record<string, unknown>;
+    timestamp: number;
+}
+/**
+ * 业务线：区分使用模拟器的平台，作为公共字段注入每条打点。
+ * 由接入方自定义，如 `creator`（创作平台）/ `audit`（审核平台）。
+ */
+export type MiniAppBusinessLine = string;
+/** 默认上报用的用户信息：当前仅取 `userId` 作为 APM 用户标识。 */
+export interface MiniAppTrackerUserInfo {
+    userId: string;
+}
+/** APM 上报 region：`cn` 国内、`sg` 海外（rednote） */
+export type MiniAppApmRegion = 'cn' | 'sg';
+/**
+ * 默认上报选项。
+ * 走内置默认上报：直接 POST 自定义打点到 APM 端点，`business_line` 必填。
+ */
+export interface MiniAppDefaultTrackerOptions {
+    /** 业务线：区分使用模拟器的平台（必填，公共字段） */
+    business_line: MiniAppBusinessLine;
+    /**
+     * 获取当前用户信息：默认上报会取其中的 `userId` 作为 APM 用户标识注入上报。
+     * 可同步或异步返回；不提供 / 返回空时 `userId` 留空，不影响其它字段上报。
+     */
+    getUserInfo?: () => MiniAppTrackerUserInfo | Promise<MiniAppTrackerUserInfo>;
+    /** 上报 region，决定默认端点：`cn`（默认）/ `sg` */
+    region?: MiniAppApmRegion;
+    /** 覆盖 APM 上报端点 URL；传了则忽略 `region` */
+    endpoint?: string;
+    /** 打印到 console 而非真正上报；仅显式传 true 时开启。 */
+    debug?: boolean;
+    /** 附加到每条事件的稳定诊断上下文；仅用于内部链路关联，避免放入动态阶段字段。 */
+    context?: Record<string, string | number | boolean | undefined>;
+}
+/** Tracker 选项（等价于默认上报选项）。 */
+export type MiniAppTrackerOptions = MiniAppDefaultTrackerOptions;
+/**
+ * Tracker 输入：
+ * - `{ business_line }` → 内置默认上报
+ * - `false` / 不传 → 不启用
+ */
+export type MiniAppTrackerInput = MiniAppTrackerOptions | false;