@skillbuilder/miniapp-simulator 0.0.0-stage → 0.2.1

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;

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

@@ -0,0 +1,11 @@
+/**
+ * TapPlugin — 短按 tap 检测。
+ *
+ * 监听 down/up，根据时长 + 距离判定为 tap，向 iframe 发送 `mini-app:tap` 消息
+ * （receiver 端的 ClickSynthesizerPlugin 会派发 mousedown / mouseup / click）。
+ *
+ * 协议逻辑事件：
+ *   - emit "tap" { point, modifiers } —— DoubleTapPlugin 依赖此事件计数双击
+ */
+import type { GestureHostPlugin } from "../types";
+export declare function createTapPlugin(): GestureHostPlugin;

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

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

@@ -0,0 +1,11 @@
+/**
+ * WheelScrollPlugin — 鼠标滚轮 → iframe 内滚动。
+ *
+ * overlay z-index:2 完全吞掉了 wheel 事件，造成 PC 用户无法用滚轮滚动 iframe 内长列表。
+ * 本 plugin 监听 overlay 的 wheel 事件，转发到 iframe 内（receiver 端 WheelDispatchPlugin
+ * 派发原生 WheelEvent + scrollBy fallback）。
+ *
+ * 注意：Alt + wheel 不在本 plugin 处理（由 PinchPlugin 拦截作为缩放）。
+ */
+import type { GestureHostPlugin } from "../types";
+export declare function createWheelScrollPlugin(): GestureHostPlugin;

package/lib/types/gesture/receiver-runtime.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 手势 receiver 注入。逻辑源在 receiver-runtime.impl.ts，经 gen:receiver 编成
+ * receiver-runtime.impl.built.js，这里以 ?raw 内联为注入字符串。改逻辑改 impl.ts。
+ */
+export declare const RECEIVER_RUNTIME_SOURCE: string;
+/**
+ * 把 receiver runtime 注入到目标 iframe 内。
+ * 需要 iframe 已 onload + 父页面与 iframe 同源（SW 直供的同源 URL）。
+ */
+export declare function injectGestureReceiver(iframe: HTMLIFrameElement): boolean;

package/lib/types/gesture/receiver-runtime.impl.d.ts

@@ -0,0 +1,6 @@
+/**
+ * iframe 内的手势 receiver 逻辑源。由 scripts/gen-receiver-runtime.mjs 编成
+ * receiver-runtime.impl.built.js，再经 receiver-runtime.ts 以 ?raw 注入 guest 执行。
+ *
+ * 约束：不得 import/export（作为 classic script 注入）、不依赖宿主全局。
+ */

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

@@ -0,0 +1,78 @@
+/**
+ * TouchCursor —— 模拟器内置的「手指指针」。
+ *
+ * 设计取舍（见 issue 排查）：
+ *   早期把它做成 hover gesture plugin，圆点的显示依赖 host-bus 的事件管线
+ *   （rect 命中判定 + isPressed 闸门 + dispatch("move") + plugin 订阅）。
+ *   任一环节静默不触发，圆点就出不来——实际表现为「按压才出现，移入即消失」。
+ *
+ *   touch 指针是触摸模拟的核心视觉，不属于可插拔行为。这里抽成独立类，
+ *   由 gesture 核心（GestureHostBus）直接持有，圆点元素**即时创建**，
+ *   显示/跟随完全走自己的原始鼠标监听，不经过任何闸门，确保稳定。
+ *
+ * 三态（设计走查：指针只用白色，不随状态变蓝/变红）：
+ *   idle    白色玻璃质感空心圆 24px（普通区域）
+ *   hot     与 idle 同（指向 cursor=pointer/grab 的元素，仅描边略加重反馈）
+ *   pressed 白色实心圆 22px（按下中，长宽 -2px 给反馈）
+ *
+ * hot 判定需要 iframe 与父页面同源（读 elementFromPoint 的 computed cursor）。
+ */
+export interface TouchCursorOptions {
+    /** 圆点的「可视区域」：判定指针是否在模拟器内（用稳定的 light DOM 元素，如 shadow host） */
+    region: HTMLElement;
+    /** 内容载体元素（iframe 或 webview），仅用于 hot 命中范围判定 */
+    element: HTMLElement;
+    /** 载体区域遮罩：用于按压检测，并同步隐藏系统鼠标 */
+    overlay: HTMLElement;
+    /**
+     * 读 host 视口坐标下 guest 元素的 computed cursor（hot 判定）。
+     * iframe 同源可同步读取；webview 跨进程返回 undefined → hot 降级（恒不高亮）。
+     */
+    readCursor?: (hostX: number, hostY: number) => string | undefined;
+}
+export declare class TouchCursor {
+    private readonly region;
+    private readonly element;
+    private readonly overlay;
+    private readonly readCursor?;
+    private readonly dot;
+    private destroyed;
+    /** DevTools 审查等场景暂时禁止显示/跟随，避免挡住 Elements 选点 */
+    private suppressed;
+    private visible;
+    private pressed;
+    private hot;
+    /** 当前宿主视口坐标 */
+    private hostX;
+    private hostY;
+    private rafId;
+    /** 进入触摸模拟前 region 的内联 cursor，销毁时还原 */
+    private readonly savedRegionCursor;
+    private readonly savedOverlayCursor;
+    constructor(options: TouchCursorOptions);
+    /**
+     * 指针下的「最顶层」元素是否属于模拟器（穿过 shadow 边界判定）。
+     *
+     * 不能只用 region 矩形几何判定：消费方在模拟器之上叠加的弹窗（如扫码预览模态）
+     * 虽落在 region 矩形内，但它才是指针下的真实命中元素。圆点是 z-index 99999 的
+     * fixed 层，若仅靠几何就会画到弹窗之上（视觉「穿透」）。
+     * 改用事件 composedPath：仅当模拟器自身元素（shadow host / overlay / 载体）在命中
+     * 链上，才认为指针确实落在模拟器、且模拟器是最顶层，圆点才显示。
+     */
+    private isTopmostSimulator;
+    private applyMode;
+    private place;
+    private refreshMode;
+    private show;
+    private hide;
+    /** hot 判定：经介质通道读指针下元素的 computed cursor（RAF 节流，跨边界 getComputedStyle 昂贵） */
+    private tickHot;
+    /** DevTools 审查 / 权限弹窗 / 元素选取等场景：隐藏圆点并暂停跟随，避免干扰上层交互 */
+    setSuppressed(suppressed: boolean): void;
+    private onMove;
+    private onLeave;
+    private onDown;
+    private onUp;
+    private onBlur;
+    destroy(): void;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * 触点圆点工具：在父窗口上画固定定位的圆点，用于可视化触摸位置。
+ * 多个 plugin 共享（SingleTouch 主触点、MultiTouchHint 副触点、Pinch 双指等）。
+ */
+export declare class TouchDotManager {
+    private readonly dots;
+    private readonly parent;
+    constructor(parent?: HTMLElement);
+    place(id: number, clientX: number, clientY: number, color?: string): void;
+    remove(id: number): void;
+    clear(): void;
+}

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

@@ -0,0 +1,206 @@
+/**
+ * Gesture 模块的核心类型。
+ *
+ * 设计目标：
+ * - 把"宿主鼠标 → iframe 内 touch/click/wheel 等"全部抽成插件化协议
+ * - host 端 plugin 监听原始事件并 send 给 iframe，receiver 端 plugin 派发对应 DOM 事件
+ * - 跨 plugin 通过共享状态 + 逻辑事件 emit/on 协作
+ */
+export interface GesturePoint {
+    identifier: number;
+    clientX: number;
+    clientY: number;
+    pageX: number;
+    pageY: number;
+    screenX: number;
+    screenY: number;
+}
+export interface ModifierKeys {
+    altKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    shiftKey: boolean;
+}
+/**
+ * 原始指针事件快照（在 host 端已转换为 iframe CSS 坐标 + host 坐标双坐标空间）。
+ * 所有 host plugin 看到的都是这种统一格式，不直接接触 DOM Event。
+ */
+export interface PointerSnapshot {
+    kind: "down" | "move" | "up" | "leave" | "wheel" | "blur";
+    /** iframe CSS 坐标空间（已做 transform scale 修正） */
+    iframeX: number;
+    iframeY: number;
+    /** 宿主视口坐标（用于 overlay 上画 UI） */
+    hostX: number;
+    hostY: number;
+    /** screen 坐标（透传给合成事件） */
+    screenX: number;
+    screenY: number;
+    modifiers: ModifierKeys;
+    /** 0=left, 1=middle, 2=right；wheel/blur 时为 0 */
+    button: number;
+    /** 仅 wheel 时有值 */
+    wheelDeltaX?: number;
+    wheelDeltaY?: number;
+    wheelDeltaMode?: number;
+    timestamp: number;
+    /** 原始 DOM 事件，plugin 可用其 preventDefault；blur 时为 null */
+    raw: MouseEvent | WheelEvent | null;
+}
+/** 宿主侧可回放的通用手势输入，坐标使用 guest CSS 像素。 */
+export type GestureDispatchAction = "tap" | "doubleTap" | "longPress" | "scroll" | "swipe";
+export interface GestureDispatchInput {
+    action: GestureDispatchAction;
+    x: number;
+    y: number;
+    toX?: number;
+    toY?: number;
+    deltaX?: number;
+    deltaY?: number;
+    duration?: number;
+}
+export interface GestureDispatchResult {
+    action: GestureDispatchAction;
+    from: {
+        x: number;
+        y: number;
+    };
+    to?: {
+        x: number;
+        y: number;
+    };
+    segments?: number;
+    durationMs?: number;
+}
+export type GestureBusMessage = TouchMessage | WheelMessage | TapMessage | LongPressMessage | DoubleTapMessage | CursorQueryMessage | SelectionMessage;
+export interface TouchMessage {
+    type: "mini-app:touch";
+    eventName: "touchstart" | "touchmove" | "touchend" | "touchcancel";
+    touches: GesturePoint[];
+    changedTouches: GesturePoint[];
+    modifiers: ModifierKeys;
+}
+export interface WheelMessage {
+    type: "mini-app:wheel";
+    iframeX: number;
+    iframeY: number;
+    deltaX: number;
+    deltaY: number;
+    deltaZ: number;
+    deltaMode: number;
+    modifiers: ModifierKeys;
+}
+export interface TapMessage {
+    type: "mini-app:tap";
+    point: GesturePoint;
+    modifiers: ModifierKeys;
+}
+export interface LongPressMessage {
+    type: "mini-app:longpress";
+    point: GesturePoint;
+    modifiers: ModifierKeys;
+}
+export interface DoubleTapMessage {
+    type: "mini-app:dblclick";
+    point: GesturePoint;
+    modifiers: ModifierKeys;
+}
+export interface CursorQueryMessage {
+    type: "mini-app:cursor-query";
+    iframeX: number;
+    iframeY: number;
+    /** 关联 ID，回包用同样 ID 携带 cursor 字符串 */
+    queryId: number;
+}
+export interface CursorReplyMessage {
+    type: "mini-app:cursor-reply";
+    queryId: number;
+    cursor: string;
+}
+export interface SelectionMessage {
+    type: "mini-app:selection";
+    enabled: boolean;
+}
+/** guest → host 回包（receiver 主动上报，如 focus-editable / cursor-reply） */
+export interface GestureInboundMessage {
+    type?: string;
+    [key: string]: unknown;
+}
+/**
+ * 手势「介质通道」——封装 host↔guest 的发送/回包/聚焦/cursor 读取差异。
+ *
+ * - iframe：`send` 走 `contentWindow.postMessage`；`subscribe` 监听 `window.message`
+ *   （source 过滤）；`readCursorAt` 同步读 `contentDocument` 的 computed cursor。
+ * - webview：`send` 走 `WebviewTransport`（IPC `mas:msg` → preload 转成 guest
+ *   `window.message` 喂给 receiver）；`subscribe` 走 `transport.onMessage`；
+ *   `readCursorAt` 跨进程无法同步读取 → 返回 `undefined`（hot 高亮降级）。
+ */
+export interface GestureGuestChannel {
+    /** host → guest 发送手势协议消息 */
+    send(msg: GestureBusMessage): void;
+    /** 订阅 guest → host 回包；返回取消订阅 */
+    subscribe(handler: (msg: GestureInboundMessage) => void): () => void;
+    /** guest 内表单聚焦后，把宿主焦点切到 guest（键盘输入可达） */
+    focusGuest(): void;
+    /** 读 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 {
+    /** 鼠标主按键是否处于按下态 */
+    isPressed: boolean;
+    /** 是否进入多指模式（任意 MultiTouchSwitch/Pinch/Rotate plugin 控制） */
+    isMultiTouch: boolean;
+    /** 双指模式时的算法，single touch 时为 null */
+    multiTouchMode: MultiTouchMode | null;
+    /** 多指基点：双指对称中心 */
+    multiTouchBase: {
+        hostX: number;
+        hostY: number;
+        iframeX: number;
+        iframeY: number;
+    } | null;
+    /** 当前按下起点（用于 tap/longpress 距离阈值判定） */
+    pressStartPoint: {
+        iframeX: number;
+        iframeY: number;
+        hostX: number;
+        hostY: number;
+    } | null;
+    pressStartedAt: number;
+}
+export type RawEventName = PointerSnapshot["kind"];
+export type RawEventHandler = (ev: PointerSnapshot) => void;
+export type LogicEventHandler = (...args: unknown[]) => void;
+export interface GestureHostContext {
+    /** 订阅原始指针事件 */
+    on(event: RawEventName, handler: RawEventHandler): () => void;
+    /** 跨 plugin 协作：触发逻辑事件 */
+    emit(event: string, ...args: unknown[]): void;
+    /** 订阅逻辑事件（例如 'tap' / 'longpress' / 'pinch' / 'rotate'） */
+    hook(event: string, handler: LogicEventHandler): () => void;
+    /** 把消息发到 guest 内（介质相关：postMessage / IPC 包装） */
+    send(msg: GestureBusMessage): void;
+    /** 共享状态（跨 plugin 读写） */
+    readonly state: GestureSharedState;
+    /** overlay DOM 节点，plugin 可往里加触点圆点 / 状态条等 UI */
+    readonly overlay: HTMLDivElement;
+    /** 目标内容载体元素（iframe 或 webview，仅用于坐标/聚焦，与介质无关） */
+    readonly iframe: HTMLElement;
+    /** 设置 overlay 的 cursor（HoverIndicatorPlugin 主要用，默认隐藏成 "none"） */
+    setCursor(cursor: string): void;
+    /** debug 开关 */
+    readonly debug: boolean;
+}
+export interface GestureHostPlugin {
+    readonly name: string;
+    install(ctx: GestureHostContext): void;
+    /** 可选清理钩子，bus.dispose 时调用 */
+    uninstall?(): void;
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Shadow Host：把模拟器核心渲染在消费方提供的 root 节点内部，并用 Shadow DOM 隔离样式。
+ *
+ * DOM 结构：
+ *   root（消费方传入，如 #preview）
+ *     host（SDK 创建的宿主元素，撑满 root）
+ *       #shadow-root（shadow=true 时）
+ *         <style> base reset </style>
+ *         bounds（.dms-bounds，stageFit 的可用区域 / 默认 bounds）
+ *           stage（.dms-stage，渲染器实际挂载点，等价于旧的 container）
+ *
+ * shadow=false 时不创建 shadow root，bounds/stage 直接挂在 host 的 light DOM 下，
+ * 仅依赖内联样式（手机壳 / 内容层 / 手柄本身就是内联样式，自定义元素自带 :host 样式）。
+ */
+/** 挂载目标：CSS 选择器字符串或 HTMLElement */
+export type MiniAppMountTarget = string | HTMLElement;
+export interface CreateShadowHostOptions {
+    /** 是否启用 Shadow DOM 隔离，默认 true */
+    shadow?: boolean;
+}
+export interface MiniAppShadowHost {
+    /** 消费方提供的 root 节点 */
+    root: HTMLElement;
+    /** SDK 在 root 内创建的宿主元素 */
+    host: HTMLElement;
+    /** Shadow Root；shadow=false 时为 null */
+    shadowRoot: ShadowRoot | null;
+    /** stageFit 的默认可用区域（bounds） */
+    bounds: HTMLElement;
+    /** 渲染器实际挂载点（等价于旧 container） */
+    stage: HTMLElement;
+    /** 宿主侧 overlay（如 toast）应挂载到的根：shadowRoot 或 host */
+    overlayRoot: ShadowRoot | HTMLElement;
+    /** 销毁：移除创建的宿主元素 */
+    destroy(): void;
+}
+/** 解析挂载目标为 HTMLElement（字符串走 querySelector） */
+export declare function resolveMountRoot(target: MiniAppMountTarget): HTMLElement;
+/** 在 root 内创建宿主元素 + （可选）Shadow Root + bounds + stage */
+export declare function createShadowHost(root: HTMLElement, options?: CreateShadowHostOptions): MiniAppShadowHost;

package/lib/types/index.d.ts

@@ -0,0 +1,56 @@
+export { createMiniAppSimulator } from "./core/simulator";
+export { BusinessLine } from "./business-line";
+export { MiniAppSimulatorError } from "./errors";
+export { MiniAppJsApiErrorCode } from "./types";
+export { WORKER_CONTENT_SECURITY_POLICY } from "./worker/adapters/protocol";
+export type { WorkerGuardConfig } from "./worker/adapters/protocol";
+export declare const WORKER_RUNTIME_METADATA: Readonly<import("./worker/adapters/protocol").WorkerRuntimeMetadata>;
+export { WORKER_RUNTIME_PROTOCOL_VERSION } from "./worker/adapters/protocol";
+export type { MiniAppWorkerOptions } from "./worker/adapters/package-policy";
+export type { WorkerCspPolicy } from "./worker/adapters/csp-policy";
+export { detectEnvironment, getSimulatorContext, type SimulatorEnvironment, type SimulatorRuntimeContext, } from "./runtime/context";
+/**
+ * 设备能力白名单枚举与元数据，供 `security.sealAllow` 配置 / UI 枚举渲染 / 校验。
+ * 由模拟器维护，供消费方一处引入。
+ */
+export { ALL_MINI_APP_CAPABILITIES, HOST_CONTROLLED_CAPABILITIES, MINI_APP_CAPABILITIES, MiniAppCapability, type MiniAppCapabilityControlledBy, type MiniAppCapabilityDescriptor, SEAL_CONTROLLED_CAPABILITIES, isMiniAppCapability, sanitizeCapabilityList, } from "./seal-config";
+export type { 
+/** 创建参数 */
+MiniAppSimulatorOptions, 
+/** 实例类型（含 loadZip / on / notePreview 等） */
+MiniAppSimulator, MiniAppGamePlaytestController, 
+/** switchContentMode / contentMode 字段 */
+MiniAppContentMode, 
+/** shell 字段：rednote 笔记壳 / none 无壳纯面板 */
+MiniAppShellMode, 
+/** renderer 字段：webview / iframe-service-worker */
+MiniAppRendererType, 
+/** REDNote 壳层笔记数据（notePreview.update / updateUser / updateAppCard） */
+XhsNotePreviewData, 
+/** 壳层顶栏用户信息（notePreview.updateUser） */
+XhsNotePreviewUser, 
+/** 笔记内小工具入口卡片信息（notePreview.updateAppCard） */
+XhsNoteAppCardData, 
+/** 小工具封面（widgetCover.update；笔记尾卡 + 个人页卡片两处生效） */
+XhsWidgetCoverData, 
+/** 页面路由：redirectTo / getCurrentRoute / routerChange 事件 */
+MiniAppSimulatorRoute, MiniAppRedirectOptions, 
+/** 截图：screenShot() 结果 */
+MiniAppScreenShotResult, MiniAppScreenShotErrorCode, 
+/** simulator.on / once / off 事件名与 payload */
+MiniAppEventName, MiniAppEventHandler, MiniAppEventMap, MiniAppGestureController, GestureDispatchAction, GestureDispatchInput, GestureDispatchResult, 
+/** 可视化元素选取：控制器 / 选区描述 / 状态事件 */
+MiniAppInspectorController, ElementSelection, ElementPathSegment, MiniAppInspectorSelectionMode, MiniAppElementSelectionChangeEvent, MiniAppVisualSelectionChangeEvent, VisualSelection, SceneSelection, MiniAppSceneNode, MiniAppScenePathSegment, MiniAppSceneProviderTree, MiniAppSceneSourceHint, MiniAppSceneTreeSnapshot, MiniAppInspectorChangeEvent, 
+/** loadZip 入参 / 返回值 */
+MiniAppLoadZipOptions, MiniAppLoadZipResult, MiniAppPackageLimits, MiniAppRuntimeLimits, 
+/** loadFiles 入参 / 选项 / 返回值（AI 出码目录产物加载） */
+MiniAppFileContent, MiniAppFileMap, MiniAppLoadFilesOptions, MiniAppLoadFilesResult, 
+/** options.hostApi 单条定制项：函数 handler / `{ toast }` 占位覆盖 */
+MiniAppHostApiHandler, MiniAppHostApiStub, MiniAppHostApiEntry, MiniAppHostApiRequest, MiniAppHostRequest, MiniAppHostRequestOptions, MiniAppHostRequestResponse, 
+/** options.tracker：输入 / 选项 / 上报事件 / 业务线 / region */
+MiniAppTrackerInput, MiniAppTrackerOptions, MiniAppDefaultTrackerOptions, MiniAppTrackerEvent, MiniAppTrackerUserInfo, MiniAppBusinessLine, MiniAppApmRegion, } from "./types";
+/** DOM 元素结构化定位工具，供同源预览宿主复用 */
+export { buildElementSelection, computeSelector } from "./inspector";
+/** `screenShot` 失败码常量（notLoaded / renderFailed / timeout / unsupported） */
+export { MINIAPP_SCREENSHOT_ERROR_CODE } from "./types";
+export type { WorkerTerminateFlag, WorkerTerminateCallback, WorkerRuntimeState, } from "./worker/adapters/protocol";

package/lib/types/injection/guest-log-mark.d.ts

@@ -0,0 +1,7 @@
+/** guest 内框架注入脚本的日志前缀；host 据此把 console 的 source 标为 `sdk` */
+export declare const MINIAPP_SDK_LOG_MARK = "[mini-app-sdk]";
+/** 按框架标记判定 console 来源；sdk 日志剥掉前缀 */
+export declare function classifyConsoleMessage(raw: string): {
+    message: string;
+    source: "sdk" | "user";
+};

package/lib/types/injection/head-builder.d.ts

@@ -0,0 +1,4 @@
+import type { InjectionRegistry } from "./registry";
+import type { InjectionContext } from "./types";
+/** 装配 head：meta/style 在前，内部模块脚本收口进单个（带 nonce 的）`<script>`，逐段 try/catch。 */
+export declare function assembleHeadInjection(injection: InjectionRegistry, ctx: InjectionContext): Promise<string>;

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

@@ -0,0 +1,19 @@
+/**
+ * Injection 层统一出口（注入模块清单 + builders + 内置模块）。
+ *
+ * Kernel 与 Plugin 内部使用本文件统一导入；不对宿主暴露。
+ */
+export { InjectionRegistry } from "./registry";
+export type { InjectionContext, InjectionModule } from "./types";
+export { assembleHeadInjection } from "./head-builder";
+export { buildWebviewPreloadSource, materializePreloadFile, materializeWebviewPreload, } from "./preload-builder";
+export type { BuildWebviewPreloadOptions } from "./preload-builder";
+export { renderDoneInjection } from "./modules/render-done";
+export { jsapiInjection } from "./modules/jsapi";
+export { securityInjection } from "./modules/security";
+export { consoleForwardInjection } from "./modules/console-forward";
+export { inspectorInjection } from "./modules/inspector";
+export { resourceGuardInjection } from "./modules/resource-guard";
+export { gestureReceiverInjection } from "./modules/gesture";
+export { scrollContainmentInjection } from "./modules/scroll-containment";
+export { widgetSnapshotInjection } from "./modules/widget-snapshot";

package/lib/types/injection/modules/console-forward.d.ts

@@ -0,0 +1,2 @@
+import type { InjectionModule } from "../types";
+export declare const consoleForwardInjection: InjectionModule;

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

@@ -0,0 +1,6 @@
+import type { InjectionModule } from "../types";
+/**
+ * iframe 手势接收器必须随 HTML 一起注入：跨站 OOPIF 加载完成后，宿主无法再访问
+ * contentDocument 动态插入脚本。webview 仍由 preload-builder 单独装配 receiver。
+ */
+export declare const gestureReceiverInjection: InjectionModule;

package/lib/types/injection/modules/inspector-guest-runtime.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Visual Inspector 在 guest document 中运行的逻辑源。
+ *
+ * 约束：不得 import/export，不依赖宿主模块；构建时会作为 classic script 注入。
+ */

package/lib/types/injection/modules/inspector-pause-runtime.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Visual Inspector 通用暂停时钟。
+ *
+ * 约束：不得 import/export，不依赖宿主模块；构建时会作为 classic script 注入。
+ * 在业务脚本执行前代理 RAF 与 timer，进入圈选时冻结，退出时按剩余时间恢复。
+ */

package/lib/types/injection/modules/inspector.d.ts

@@ -0,0 +1,8 @@
+import type { InjectionModule } from "../types";
+/**
+ * Visual Inspector guest bridge。
+ *
+ * 逻辑实现在可独立类型检查的 inspector-guest-runtime.ts 中；Vite 构建时通过
+ * `?injected-runtime` 将其编译成 classic-script 字符串，避免在宿主源码里维护转义代码。
+ */
+export declare const inspectorInjection: InjectionModule;

package/lib/types/injection/modules/jsapi-channel.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Guest-side bridge source injected before the client JS API UMD.
+ *
+ * iframe guests post directly to their parent. A top-level Electron webview
+ * posts to itself, which the simulator's webview preload forwards over IPC.
+ */
+export declare const SIMULATOR_JSAPI_CHANNEL_SOURCE: string;
+/** Signal readiness only after the client JS API UMD has installed successfully. */
+export declare const SIMULATOR_JSAPI_CHANNEL_READY_SOURCE: string;

package/lib/types/injection/modules/jsapi.d.ts

@@ -0,0 +1,22 @@
+import type { InjectionModule } from "../types";
+/**
+ * jsapi 注入模块：按启动参数→模拟器通道→客户端 jsapi 的顺序注入到子文档执行环境。
+ *
+ * 注入策略：
+ *   - `mode: 'auto'`：若检测到原 HTML 已自带 jsapi（meta 或 script），跳过；
+ *     否则注入启动参数、模拟器通道和客户端 UMD
+ *   - `mode: 'external'`：注入容器启动参数和模拟器通道，JS SDK 由业务自管
+ *   - `mode: 'off'` / `jsapi.enabled = false`：仅注入容器启动参数
+ *
+ * 介质适配：
+ *   - iframe/SW：作为 head 合并 `<script>` 的一段
+ *   - webview：写入 preload 体内（preload 在 document-start 执行，等同时机）
+ *
+ * 注：detect external 仅在 iframe 路径生效（webview 拿不到原 HTML）；
+ * webview 默认按 enabled 决定。
+ */
+/** 与客户端共用的 JS API UMD，不包含模拟器通道实现。 */
+export declare const BUNDLED_CLIENT_JSAPI_SCRIPT: string;
+/** 检测原 HTML 是否已自带 jsapi（meta 显式声明或 script 引入） */
+export declare function detectExternalJsApi(rawHtml: string): boolean;
+export declare const jsapiInjection: InjectionModule;

package/lib/types/injection/modules/render-done.d.ts

@@ -0,0 +1,2 @@
+import type { InjectionModule } from "../types";
+export declare const renderDoneInjection: InjectionModule;

package/lib/types/injection/modules/resource-guard.d.ts

@@ -0,0 +1,7 @@
+import type { InjectionModule } from "../types";
+/**
+ * Guest 资源保护：不改写任何浏览器内置 API；卸载时做 best-effort 媒体/Canvas 清理，
+ * 并对既有 WebGL 上下文调用标准的 WEBGL_lose_context 主动归还显存（显存不经 V8 GC 回收）。
+ * Chromium 可提供 performance.memory 时，按 renderer 总 JS heap 绝对水位熔断失控业务。
+ */
+export declare const resourceGuardInjection: InjectionModule;

package/lib/types/injection/modules/scroll-containment.d.ts

@@ -0,0 +1,3 @@
+import type { InjectionModule } from "../types";
+/** 必须早于业务脚本：小应用加载阶段的首次滚动调用就足以把宿主页拽走。 */
+export declare const scrollContainmentInjection: InjectionModule;

package/lib/types/injection/modules/security.d.ts

@@ -0,0 +1,3 @@
+import type { InjectionModule } from "../types";
+/** security 注入：head meta + `<style>`，head 脚本 seal，webview preload seal。 */
+export declare const securityInjection: InjectionModule;

package/lib/types/injection/modules/widget-snapshot.d.ts

@@ -0,0 +1,13 @@
+import type { InjectionModule } from "../types";
+/**
+ * 小工具截图与首次绘制回报注入模块。
+ *
+ * head 合并脚本内执行：
+ *   - 监听宿主 `mini-app:widget-snapshot-request`，用 html-to-image 在 guest 上下文
+ *     截取自身文档（抓取 SW 虚拟资源），回传 blob
+ *   - 观察 FCP / LCP（已绘制的立即回报），首次绘制后向宿主回报
+ *     `mini-app:widget-first-paint-report`，宿主（远程 Runtime）据此触发自动截图
+ *
+ * 介质适配：仅 iframe（html-to-image 依赖 guest DOM）；webview 截图走原生 capture。
+ */
+export declare const widgetSnapshotInjection: InjectionModule;

package/lib/types/injection/preload-builder.d.ts

@@ -0,0 +1,41 @@
+import type { NormalizedMiniAppSimulatorOptions } from "../types";
+import type { InjectionRegistry } from "./registry";
+/**
+ * webview preload 拼装入口。
+ *
+ * 拼接逻辑：
+ *   1. **通道桥接 IIFE**（固定，来自 `transport/webview-preload.js`）：
+ *      建立 `window.message ↔ ipcRenderer.sendToHost` 双向转发。
+ *   2. **业务注入**（按当前 options 烤进去）：遍历 InjectionRegistry 的
+ *      `buildPreloadSource`，包含 jsapi UMD / seal IIFE / render-done 等。
+ *
+ * 两段拼好后写入临时 `file://`，挂到 `<webview preload="...">`。
+ * Electron 在 webview 进程 document-start 阶段加载执行——
+ * **完全不依赖** `webview.executeJavaScript`（webview 业务能力**不存在** dom-ready 后注入这种路径）。
+ *
+ * 时序：每次 simulator load 都重新 materialize，options 变更会自动反映到下一次 preload。
+ */
+export interface BuildWebviewPreloadOptions {
+    options: NormalizedMiniAppSimulatorOptions;
+    injection: InjectionRegistry;
+    /** 已知 url（如有，供 base 等场景；preload 不直接需要） */
+    appUrl?: string;
+}
+/**
+ * 一站式：拼装 preload 源码 + 写入临时 file，返回 `file://` URL。
+ * 仅 Electron renderer 环境可用；其它环境返回 null。
+ */
+export declare function materializeWebviewPreload(buildOptions: BuildWebviewPreloadOptions): Promise<string | null>;
+/**
+ * 拼接完整 preload 源码（通道桥接 + 业务注入），不写文件。
+ * 单独导出便于测试 / debug 输出。
+ */
+export declare function buildWebviewPreloadSource(buildOptions: BuildWebviewPreloadOptions): Promise<string>;
+/**
+ * 把 preload 源串物化为 `file://` URL。
+ *
+ * - 写入 `os.tmpdir()/miniapp-simulator-preload/preload-<sha1>.js`
+ * - sha1 取自源码内容，便于幂等复用
+ * - 不可用环境（无 require）返回 null
+ */
+export declare function materializePreloadFile(source: string): Promise<string | null>;