@skillbuilder/miniapp-simulator 0.0.0-stage → 0.2.1

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

@@ -0,0 +1,165 @@
+import type { BusinessLine } from "../business-line";
+import type { ManagedRequestChunk, ManagedRequestHeaders, ManagedRequestOptions, ManagedRequestResult } from "../runtime/request/request-types";
+import type { MiniAppContentMode, MiniAppFileMap, MiniAppHostApiRequest, MiniAppInspectorSelectionMode, MiniAppLoadFilesOptions, MiniAppLoadZipOptions, MiniAppRedirectOptions, MiniAppSecurityOptions, MiniAppSimulatorOptions, MiniAppSimulatorRoute, MiniAppViewport } from "../types";
+/**
+ * 远程模拟器通信协议版本。单一来源是同目录的 protocol-version.json，
+ * 发布脚本（scripts/publish-assets.mjs）、server dev 接口与压测脚本都从该文件读取。
+ */
+export declare const REMOTE_SIMULATOR_PROTOCOL_VERSION: number;
+export declare const REMOTE_SIMULATOR_CONNECT = "miniapp-simulator:connect";
+/** Runtime 已包含可在圈选期间冻结 RAF/timer/CSS/media 的 guest 注入能力。 */
+export declare const REMOTE_INSPECTOR_PAUSE_RUNTIME_CAPABILITY = "inspectorPauseRuntime";
+export declare const REMOTE_SIMULATOR_CAPABILITIES: string[];
+export type RemoteSimulatorSerializableOptions = Omit<MiniAppSimulatorOptions, "mount" | "appId" | "renderer" | "serviceWorker" | "security" | "jsapi" | "hostApi" | "tracker" | "runtimeLimits" | "onEvent" | "onReady" | "onBeforeLoad" | "onLoad" | "onRenderDone" | "onError" | "onNavigation" | "onConsole" | "onNetwork" | "onDestroy" | "onRouterChange" | "onScreenShot"> & {
+    appUrl?: string;
+    /** 包会话 Worker 开关；Worker CSP 由 Runtime 服务配置。 */
+    security?: Pick<MiniAppSecurityOptions, "worker">;
+};
+export interface RemoteSimulatorGatewayOptions {
+    edith: string;
+    www: string;
+    [name: string]: string;
+}
+export interface RemoteSimulatorConnectMessage {
+    type: typeof REMOTE_SIMULATOR_CONNECT;
+    protocolVersion: number;
+    sessionId: string;
+    appId: string;
+    businessLine: BusinessLine;
+    tracker: boolean;
+    gateway?: RemoteSimulatorGatewayOptions;
+    userInfo?: Record<string, unknown>;
+    hostApiMethods: string[];
+    hostApiStubs: Record<string, {
+        toast: string;
+    }>;
+    options: RemoteSimulatorSerializableOptions;
+}
+export interface RemoteSimulatorReadyMessage {
+    type: "ready";
+    protocolVersion: number;
+    runtimeVersion: string;
+    capabilities: string[];
+}
+export interface RemoteSimulatorRequestMessage {
+    type: "request";
+    requestId: string;
+    method: RemoteSimulatorMethod;
+    args: unknown[];
+}
+export interface RemoteSimulatorResponseMessage {
+    type: "response";
+    requestId: string;
+    ok: boolean;
+    result?: unknown;
+    error?: {
+        message: string;
+        code?: string;
+    };
+}
+export interface RemoteSimulatorEventMessage {
+    type: "event";
+    event: string;
+    payload: unknown;
+}
+/** Runtime 请求宿主执行不可序列化的 hostApi handler。 */
+export interface RemoteHostApiRequestMessage {
+    type: "host-api-request";
+    requestId: string;
+    event: string;
+    request: MiniAppHostApiRequest;
+}
+/** 宿主执行 hostApi handler 后回传给 Runtime。 */
+export interface RemoteHostApiResponseMessage {
+    type: "host-api-response";
+    requestId: string;
+    ok: boolean;
+    result?: unknown;
+    error?: {
+        message: string;
+        code?: string;
+    };
+}
+/** Runtime 请求宿主通用 HTTP 执行器发起请求。 */
+export interface RemoteHostRequestMessage {
+    type: "host-request";
+    requestId: string;
+    options: ManagedRequestOptions;
+}
+/** 宿主侧 SDK 适配完成后向 Runtime 回传结果。 */
+export interface RemoteHostRequestResponseMessage {
+    type: "host-request-response";
+    requestId: string;
+    ok: boolean;
+    result?: ManagedRequestResult;
+    error?: {
+        message: string;
+        code?: number;
+    };
+}
+/** Runtime 取消宿主中正在执行的通用请求。 */
+export interface RemoteHostRequestAbortMessage {
+    type: "host-request-abort";
+    requestId: string;
+}
+/** 宿主侧 SDK 适配器把响应头或流式分片转发给 Runtime。 */
+export interface RemoteHostRequestEventMessage {
+    type: "host-request-event";
+    requestId: string;
+    event: "headers" | "chunk";
+    payload: ManagedRequestHeaders | ManagedRequestChunk;
+}
+export type RemoteSimulatorPortMessage = {
+    type: "worker-visibility";
+    visible: boolean;
+} | RemoteSimulatorReadyMessage | RemoteSimulatorRequestMessage | RemoteSimulatorResponseMessage | RemoteSimulatorEventMessage | RemoteHostApiRequestMessage | RemoteHostApiResponseMessage | RemoteHostRequestMessage | RemoteHostRequestResponseMessage | RemoteHostRequestAbortMessage | RemoteHostRequestEventMessage;
+export type RemoteSimulatorMethod = "load" | "loadZip" | "loadFiles" | "loadApp" | "unload" | "reload" | "setViewport" | "switchContentMode" | "switchPhoneFrame" | "switchDevice" | "setTouchEmulation" | "permissionSheet.show" | "permissionSheet.hide" | "notePreview.update" | "notePreview.updateUser" | "notePreview.updateAppCard" | "widgetCover.update" | "router.redirectTo" | "router.getRoute" | "inspector.enable" | "inspector.disable" | "inspector.toggle" | "inspector.clear" | "inspector.setSelectionMode" | "inspector.getSelectionMode" | "inspector.getSceneTree" | "inspector.selectByRef" | "capture" | "screenShot" | "setAutoScreenShot" | "hostApi.sync" | "hostApi.emit" | "destroy";
+export interface RemoteLoadZipArgs {
+    buffer: ArrayBuffer;
+    options?: Omit<MiniAppLoadZipOptions, "jszip">;
+}
+export interface RemoteLoadFilesArgs {
+    files: MiniAppFileMap;
+    options?: MiniAppLoadFilesOptions;
+}
+export type RemoteMethodArgumentMap = {
+    load: [];
+    loadZip: [RemoteLoadZipArgs];
+    loadFiles: [RemoteLoadFilesArgs];
+    loadApp: [string, {
+        query?: MiniAppSimulatorOptions["query"];
+    }?];
+    unload: [];
+    reload: [];
+    setViewport: [MiniAppViewport];
+    switchContentMode: [MiniAppContentMode];
+    switchPhoneFrame: [NonNullable<MiniAppSimulatorOptions["phoneFrame"]> | false];
+    switchDevice: [string];
+    setTouchEmulation: [boolean];
+    "permissionSheet.show": [string[]?];
+    "permissionSheet.hide": [];
+    "notePreview.update": [unknown];
+    "notePreview.updateUser": [unknown];
+    "notePreview.updateAppCard": [unknown];
+    "widgetCover.update": [unknown];
+    "router.redirectTo": [MiniAppSimulatorRoute, MiniAppRedirectOptions?];
+    "router.getRoute": [];
+    "inspector.enable": [];
+    "inspector.disable": [];
+    "inspector.toggle": [];
+    "inspector.clear": [];
+    "inspector.setSelectionMode": [MiniAppInspectorSelectionMode];
+    "inspector.getSelectionMode": [];
+    "inspector.getSceneTree": [];
+    "inspector.selectByRef": [string];
+    capture: [{
+        fullPage?: boolean;
+    }?];
+    screenShot: [];
+    setAutoScreenShot: [boolean];
+    "hostApi.sync": [string[], Record<string, {
+        toast: string;
+    }>];
+    "hostApi.emit": [string, unknown];
+    destroy: [string?];
+};

package/lib/types/remote/review-launch.d.ts

@@ -0,0 +1,6 @@
+export interface MarsReviewLaunchButton {
+    setStartHandler(handler: (() => Promise<void>) | null): void;
+    destroy(): void;
+}
+/** Mars Runtime 专用审核入口，挂在小工具内容页的未部署空态中。 */
+export declare function createMarsReviewLaunchButton(doc: Document, nickname?: string): MarsReviewLaunchButton;

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,14 @@
+declare global {
+    interface Window {
+        __MINIAPP_SIMULATOR_RUNTIME_CONFIG__?: RemoteRuntimeConfig;
+    }
+}
+export interface RemoteRuntimeConfig {
+    runtimeVersion: string;
+    requestManagerFrameUrl: string;
+    serviceWorkerScriptUrl: string;
+    serviceWorkerScope: string;
+    allowedParentOrigins: string[];
+    runtimeConfigUrl: string;
+}
+export declare function startRemoteMiniAppSimulatorRuntime(): void;

package/lib/types/remote/simulator-prompt.d.ts

@@ -0,0 +1,9 @@
+export interface SimulatorPromptOptions {
+    title: string;
+    content: string;
+    buttonLabel: string;
+    pendingButtonLabel?: string;
+    onButtonClick: () => void | Promise<void>;
+}
+export declare function showSimulatorPrompt(doc: Document, options: SimulatorPromptOptions): void;
+export declare function hideSimulatorPrompt(doc: Document): void;

package/lib/types/remote/widget-snapshot-guest-runtime.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,5 @@
+export { createRemoteMiniAppSimulator, type RemoteMiniAppSimulator, type RemoteMiniAppSimulatorOptions, type RemoteSimulatorEventHandler, } from "./remote/client";
+export { BusinessLine } from "./business-line";
+export { REMOTE_INSPECTOR_PAUSE_RUNTIME_CAPABILITY, REMOTE_SIMULATOR_PROTOCOL_VERSION, type RemoteSimulatorGatewayOptions, type RemoteSimulatorSerializableOptions, } from "./remote/protocol";
+export { MiniAppJsApiErrorCode, MINIAPP_SCREENSHOT_ERROR_CODE } from "./types";
+export type { MiniAppContentMode, MiniAppLoadZipResult, MiniAppHostApiController, MiniAppHostApiEntry, MiniAppHostApiHandler, MiniAppHostApiRequest, MiniAppHostRequest, MiniAppHostRequestOptions, MiniAppHostRequestResponse, MiniAppViewport, VisualSelection, XhsNoteAppCardData, XhsNotePreviewUser, XhsWidgetCoverData, MiniAppSimulatorRoute, MiniAppRedirectOptions, MiniAppScreenShotResult, MiniAppScreenShotErrorCode, MiniAppRouterChangeEvent, MiniAppSimulatorOptions, } from "./types";

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

@@ -0,0 +1,8 @@
+import { EventBus } from "../event-bus";
+import type { MiniAppEventHandler, MiniAppEventMap, MiniAppEventName } from "../types";
+export declare abstract class BaseRendererAdapter {
+    protected readonly events: EventBus;
+    on<E extends MiniAppEventName>(event: E, handler: MiniAppEventHandler<E>): () => void;
+    protected emit<E extends MiniAppEventName>(event: E, payload: MiniAppEventMap[E]): void;
+    protected clearEvents(): void;
+}

package/lib/types/renderer/content-host/iframe-content-host.d.ts

@@ -0,0 +1,84 @@
+import type { GestureDispatchInput, GestureDispatchResult } from "../../gesture/types";
+import type { GestureHostPluginLike, MiniAppViewport, VisualSelection } from "../../types";
+import type { ContentHost, ContentHostContext, GestureSetupOptions } from "./types";
+/**
+ * iframe 载体：以 `iframe.src` 直连同源 URL（SW 虚拟服务器直供，head 注入由 SW 完成），
+ * 走 IframeTransport（contentWindow.postMessage），并承载 PC 手势模拟
+ * （GestureHostBus + receiver runtime）。
+ *
+ * 尺寸策略：iframe 始终 100% 撑满父容器，逻辑视口缩放由渲染器在 contentRoot 上做。
+ */
+export declare class IframeContentHost implements ContentHost {
+    private iframe;
+    protected readonly ctx: ContentHostContext;
+    private currentUrl;
+    private detachWorkerLifecycle?;
+    private loadStartedAt;
+    private renderDoneEmitted;
+    private gestureBus;
+    private gestureSetup;
+    private resourceLimitRecovering;
+    private heapCooling;
+    private readonly pendingGesturePlugins;
+    /** 可视化元素选取器：惰性创建（首次 enableInspector），跨 reload 复用同一 iframe */
+    private inspector;
+    constructor(ctx: ContentHostContext);
+    get element(): HTMLIFrameElement;
+    private createIframe;
+    prepare(): Promise<void>;
+    afterAttached(): void;
+    private readonly handleMessage;
+    /**
+     * 先物理移除超限 Guest，再收起内容页；Runtime 只会在笔记页已恢复后收到错误事件。
+     * 这样既释放旧 iframe Realm/WebGL，又不会让审核员看到空白小工具页。
+     */
+    private handleResourceLimit;
+    /** 未启动新 Guest 时命中总堆上限：直接退回笔记页，不允许第二份应用堆叠。 */
+    private rejectLoadForResourceLimit;
+    /**
+     * 内存限制时必须移除旧 iframe，单纯导航至 about:blank 无法可靠释放旧 Realm。
+     * Renderer、Runtime 通道和设备外壳保留；手势总线仅针对替换的 iframe 重建。
+     */
+    private replaceGuestAfterResourceLimit;
+    /**
+     * 让 Guest 先执行资源释放（尤其是 `WEBGL_lose_context`）再拆 iframe。
+     * `resource-disposed` 来自内置 resource-guard；失控 Guest 不回包时以短超时继续，绝不阻塞返回笔记页。
+     */
+    private waitForGuestResourceDisposal;
+    private terminateGuest;
+    private emitRenderDone;
+    load(url: string): Promise<void>;
+    private readHostHeapUsage;
+    getLoadBlockReason(): {
+        used: number;
+        limit: number;
+    } | null;
+    private rememberHeapCooling;
+    reload(currentUrl: string): Promise<void>;
+    /** 卸载当前文档：清空 iframe 内容重置小工具运行态 */
+    unload(): void;
+    resize(_viewport: MiniAppViewport): void;
+    capture(): Promise<Blob>;
+    invokeGamePlaytest(method: "manifest" | "snapshot" | "act" | "step" | "reset" | "isAvailable", args?: unknown[]): Promise<unknown>;
+    /**
+     * iframe 介质通道：同源 iframe 可直接 postMessage / 读 contentDocument cursor。
+     */
+    private createGestureChannel;
+    setupGesture(opts: GestureSetupOptions): void;
+    private createGestureBus;
+    dispatchGesture(input: GestureDispatchInput): Promise<GestureDispatchResult>;
+    useGesturePlugin(plugin: GestureHostPluginLike): void;
+    removeGesturePlugin(name: string): boolean;
+    hasGesturePlugin(name: string): boolean;
+    listGesturePlugins(): string[];
+    setGestureOverlayInteractionEnabled(enabled: boolean): void;
+    /** 惰性创建选取器：overlay 挂到 iframe 父容器（与 iframe 盒对齐，适配各内容模式） */
+    private ensureInspector;
+    enableInspector(): void;
+    disableInspector(): void;
+    clearInspectorSelection(): void;
+    setInspectorSelectionMode(mode: import("../../types").MiniAppInspectorSelectionMode): void;
+    getInspectorSceneTree(): Promise<import("../../types").MiniAppSceneTreeSnapshot>;
+    selectInspectorByRef(ref: string): Promise<VisualSelection | null>;
+    destroy(): void;
+}

package/lib/types/renderer/content-host/index.d.ts

@@ -0,0 +1,3 @@
+export type { ContentHost, ContentHostContext, ContentHostEmit, ContentHostPlacement, GestureSetupOptions, } from "./types";
+export { IframeContentHost } from "./iframe-content-host";
+export { WebviewContentHost } from "./webview-content-host";

package/lib/types/renderer/content-host/types.d.ts

@@ -0,0 +1,89 @@
+import type { GestureDispatchInput, GestureDispatchResult, GestureHostPluginLike, MiniAppEventMap, MiniAppEventName, MiniAppViewport, RendererAdapterContext } from "../../types";
+/** 转发渲染器事件（load / error / renderDone / console / navigation / capture） */
+export type ContentHostEmit = <E extends MiniAppEventName>(event: E, payload: MiniAppEventMap[E]) => void;
+/** 载体在设备内的放置方式，决定尺寸策略 */
+export type ContentHostPlacement = "fullscreen" | "sheet";
+export interface ContentHostContext {
+    /** 渲染器上下文（jsapi / injection / normalizedOptions / transport / 等） */
+    rendererContext: RendererAdapterContext;
+    /** 把载体内部事件转发到渲染器 EventBus */
+    emit: ContentHostEmit;
+    /**
+     * 资源超限时，旧 Guest iframe 已物理移除后的宿主收尾。
+     * iframe 载体会等待该回调完成后才向 Runtime 发出错误事件，避免提示覆盖在空内容页上。
+     */
+    onResourceLimitReleased?: () => void | Promise<void>;
+    /**
+     * 放置方式：
+     * - fullscreen：直接铺满设备逻辑视口
+     * - sheet：挂在半屏 sheet body 内，撑满父容器
+     */
+    placement: ContentHostPlacement;
+}
+/** 手势接线参数（仅 iframe 载体使用） */
+export interface GestureSetupOptions {
+    /** 详情半屏外的兜底 overlay 挂载点（一般是手机壳屏幕层或 contentRoot） */
+    fallbackMountTarget: HTMLElement;
+    /** 悬停圆点跟踪区域（一般是 contentRoot，覆盖整台逻辑视口） */
+    hoverTrackTarget?: HTMLElement;
+    /** 跨 Shadow 边界的移入监听（shadow host，light DOM） */
+    hoverEnterTarget?: HTMLElement;
+}
+/**
+ * 内容载体策略：封装「iframe / webview」介质差异。
+ *
+ * 渲染器只负责设备外壳布局 + rednote 外壳挂载，载体的创建、按介质加载 URL、
+ * 通道绑定、（iframe）手势、（webview）缩放/DevTools 全部收敛到本接口的实现里。
+ */
+export interface ContentHost {
+    /** 载体根元素（iframe / webview），由渲染器挂载到 contentRoot 或 sheet body */
+    readonly element: HTMLElement;
+    /** 异步准备（webview 物化 preload）；在挂载进 DOM 之前调用 */
+    prepare(): Promise<void>;
+    /** 挂载进 DOM 之后的初始化（事件监听、transport.attach 等） */
+    afterAttached(): void;
+    /** 加载 URL（介质相关：srcdoc / src+guestUrl）；内部 emit load/error/renderDone */
+    load(url: string): Promise<void>;
+    /** 返回阻止启动新 Guest 的 renderer heap 状态；`null` 表示可启动。 */
+    getLoadBlockReason?(): {
+        used: number;
+        limit: number;
+    } | null;
+    reload(currentUrl: string): Promise<void>;
+    /** 卸载当前文档（壳层收起时调用）：清空内容重置运行态 */
+    unload?(): void;
+    /** 设置载体自身尺寸（设备壳层缩放由渲染器负责，此处仅管载体元素本身） */
+    resize(viewport: MiniAppViewport): void;
+    destroy(): void;
+    /** webview：guest webContents.setZoomFactor */
+    setZoomFactor?(factor: number): void;
+    /** webview：guest webContents id（dom-ready 后可用） */
+    getWebContentsId?(): number | null;
+    /** webview：开关 guest DevTools */
+    setDevtools?(open: boolean): void;
+    isDevtoolsOpen?(): boolean;
+    /** webview：截屏 */
+    capture?(): Promise<Blob>;
+    /** iframe/webview 统一的受控游戏测试桥调用。 */
+    invokeGamePlaytest?(method: "manifest" | "snapshot" | "act" | "step" | "reset" | "isAvailable", args?: unknown[]): Promise<unknown>;
+    dispatchGesture?(input: GestureDispatchInput): Promise<GestureDispatchResult>;
+    setupGesture?(opts: GestureSetupOptions): void;
+    useGesturePlugin?(plugin: GestureHostPluginLike): void;
+    removeGesturePlugin?(name: string): boolean;
+    hasGesturePlugin?(name: string): boolean;
+    listGesturePlugins?(): string[];
+    /** 权限弹窗打开时禁用手势 overlay 交互（仅 iframe gesture 实现） */
+    setGestureOverlayInteractionEnabled?(enabled: boolean): void;
+    /** 开启选取模式（惰性创建 overlay；同时禁用手势 overlay 交互让选取接管指针） */
+    enableInspector?(): void;
+    /** 关闭选取模式（移除 overlay；恢复手势 overlay 交互） */
+    disableInspector?(): void;
+    /** 清除当前选中高亮 */
+    clearInspectorSelection?(): void;
+    /** 设置可视化选取为单选 / 多选 */
+    setInspectorSelectionMode?(mode: import("../../types").MiniAppInspectorSelectionMode): void;
+    /** 获取 Guest Scene Provider 的只读层级树。 */
+    getInspectorSceneTree?(): Promise<import("../../types").MiniAppSceneTreeSnapshot>;
+    /** 从 Hierarchy 反向选中场景节点。 */
+    selectInspectorByRef?(ref: string): Promise<import("../../types").VisualSelection | null>;
+}

package/lib/types/renderer/content-host/webview-content-host.d.ts

@@ -0,0 +1,53 @@
+import type { GestureHostPluginLike, MiniAppViewport } from "../../types";
+import type { ContentHost, ContentHostContext, GestureSetupOptions } from "./types";
+/**
+ * webview 载体：Electron `<webview>`，独立 webContents。
+ * 通过 `src`（远程/同源 URL 直连）加载，走 WebviewTransport（IPC）。
+ *
+ * 尺寸策略：
+ * - sheet 放置：100% 撑满 sheet body（body 有确定高度，配合 webview 默认 :host flex 让内部 iframe 填满）。
+ * - fullscreen 放置：明确像素尺寸（规避内部 iframe 在百分比高度下塌成 150px）；phoneFrame 时叠加 scale。
+ */
+export declare class WebviewContentHost implements ContentHost {
+    readonly element: HTMLElement;
+    private readonly webview;
+    private readonly ctx;
+    private currentUrl;
+    private preloadUrl;
+    private domReady;
+    private devtoolsDesired;
+    private zoomFactorDesired;
+    private gestureBus;
+    private readonly pendingGesturePlugins;
+    constructor(ctx: ContentHostContext);
+    prepare(): Promise<void>;
+    afterAttached(): void;
+    load(url: string): Promise<void>;
+    reload(currentUrl: string): Promise<void>;
+    resize(_viewport: MiniAppViewport): void;
+    setZoomFactor(factor: number): void;
+    getWebContentsId(): number | null;
+    setDevtools(open: boolean): void;
+    isDevtoolsOpen(): boolean;
+    capture(): Promise<Blob>;
+    invokeGamePlaytest(method: "manifest" | "snapshot" | "act" | "step" | "reset" | "isAvailable", args?: unknown[]): Promise<unknown>;
+    /**
+     * webview 介质通道：跨进程，发送/回包都走 WebviewTransport（IPC `mas:msg`）。
+     * - send：`transport.post` → preload `ipcRenderer.on` → guest `window.message` → receiver
+     * - subscribe：`transport.onMessage`（guest 经 preload `sendToHost` 上报，如 focus-editable）
+     * - focusGuest：把宿主键盘焦点切到 webview（guest 内 editable.focus 已由 receiver 做）
+     * - readCursorAt：跨进程无法同步读 computed cursor → undefined（hot 高亮降级）
+     */
+    private createGestureChannel;
+    setupGesture(opts: GestureSetupOptions): void;
+    useGesturePlugin(plugin: GestureHostPluginLike): void;
+    removeGesturePlugin(name: string): boolean;
+    hasGesturePlugin(name: string): boolean;
+    listGesturePlugins(): string[];
+    setGestureOverlayInteractionEnabled(enabled: boolean): void;
+    destroy(): void;
+    private applyDevtools;
+    private readonly handleDomReady;
+    private readonly handleConsole;
+    private readonly handleNavigation;
+}

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

@@ -0,0 +1,93 @@
+import type { NotePublishResult, NotePublishViewData } from "../native-ui/note-publish";
+import type { MiniAppPermissionKind, MiniAppPermissionSheetResult } from "../native-ui/permission-sheet";
+import { BridgeProtocol } from "../transport";
+import type { GestureDispatchInput, GestureDispatchResult, GestureHostPluginLike, MiniAppSimulatorRoute, MiniAppViewport, NormalizedRednoteDetailSheetOptions, RendererAdapter, RendererAdapterContext, XhsNotePreviewData, XhsProfilePreviewData, XhsWidgetCoverData } from "../types";
+import { BaseRendererAdapter } from "./base";
+import type { ContentHostContext, IframeContentHost } from "./content-host";
+/**
+ * iframe 渲染器基类：负责设备外壳布局（手机壳 / 无壳标准边框 / 缩放层 contentRoot），
+ * 通过 RednoteShellMount 挂载 rednote 外壳、通过 IframeContentHost 承载 <iframe> 载体。
+ *
+ * 抽象类：内容载体由子类经 {@link createContentHost} 提供
+ * （当前唯一实现 {@link ServiceWorkerRendererAdapter} —— Web/SW 运行时）。
+ */
+export declare abstract class IframeRendererAdapter extends BaseRendererAdapter implements RendererAdapter {
+    private frame;
+    private overlay;
+    private container;
+    /** 逻辑视口尺寸的缩放层（REDNote 模式与全屏 iframe 共用） */
+    private contentRoot;
+    private rednoteShell;
+    private contentHost;
+    private currentUrl;
+    /** 与 iframe 绑定的通道；由 Kernel 创建，mount 阶段 attach，destroy 时关闭 */
+    private get transport();
+    /** 无壳纯面板模式：跳过 rednote 壳层与设备边框，内容铺满挂载区（等价裸 iframe 内嵌）。 */
+    private get chromeless();
+    /**
+     * 协议解析器；mount 阶段创建（仅当 jsapi 启用）。
+     * 暴露 public 让 simulator / native-ui 路由模块直接注册内置 jsapi handler。
+     */
+    bridge: BridgeProtocol | null;
+    private permissionSheetHost;
+    private notePublishHost;
+    private frameToastHost;
+    /** 无壳模式：同步 window `@media` 分档 */
+    private detachFramelessShellWindowSync;
+    /** 当前逻辑视口（resize 时更新，供无壳 window 同步使用） */
+    private viewport;
+    /** 卸载 contentRoot 上的 PC 行为拦截 */
+    private detachContentPcGuard;
+    private readonly context;
+    /** 把 ContentHost 内部事件转发到本渲染器 EventBus */
+    private readonly forwardEmit;
+    constructor(context: RendererAdapterContext);
+    mount(container: HTMLElement): void;
+    /** 无壳模式：挂载 window resize 同步（对齐 Vue `@media` 分档） */
+    private attachFramelessShellIfNeeded;
+    /** 创建内容载体；由子类（如 SW 渲染器）提供具体载体实现。 */
+    protected abstract createContentHost(ctx: ContentHostContext): IframeContentHost;
+    private setupBridge;
+    private setupGesture;
+    showPermissionSheet(kinds?: MiniAppPermissionKind[]): Promise<MiniAppPermissionSheetResult>;
+    hidePermissionSheet(): void;
+    showNotePublish(data: NotePublishViewData): Promise<NotePublishResult>;
+    hideNotePublish(): void;
+    showToast(text: string, options?: {
+        duration?: number;
+    }): void;
+    load(url: string): Promise<void>;
+    reload(): Promise<void>;
+    unload(): void;
+    capture(): Promise<Blob>;
+    invokeGamePlaytest(method: "manifest" | "snapshot" | "act" | "step" | "reset" | "isAvailable", args?: unknown[]): Promise<unknown>;
+    dispatchGesture(input: GestureDispatchInput): Promise<GestureDispatchResult>;
+    /** 壳层收起（下滑 / 全屏返回）：卸载内容载体文档，重置小工具运行态 */
+    private suspendContent;
+    /** 壳层重新唤起：按当前 url 重新加载 */
+    private resumeContent;
+    /** 点击“用一用”前的 heap 准入：拒绝时保持笔记页，由 Runtime 展示现有底部提示。 */
+    private allowContentOpen;
+    /** 资源超限后的 Guest 已释放，此时收起 sheet，避免暴露空 iframe。 */
+    private returnToNoteAfterResourceLimit;
+    syncRednotePreviewContext(notePreview: XhsNotePreviewData, rednoteDetail: NormalizedRednoteDetailSheetOptions): void;
+    syncProfilePreviewContext(profilePreview: XhsProfilePreviewData): void;
+    syncWidgetCoverContext(widgetCover: XhsWidgetCoverData): void;
+    setActivePage(page: Extract<MiniAppSimulatorRoute, "note" | "profile">): void;
+    openContent(sheetMode: "half" | "full"): void;
+    closeContent(): Promise<void>;
+    resize(viewport: MiniAppViewport): void;
+    useGesturePlugin(plugin: GestureHostPluginLike): void;
+    removeGesturePlugin(name: string): boolean;
+    hasGesturePlugin(name: string): boolean;
+    listGesturePlugins(): string[];
+    setGestureOverlayInteractionEnabled(enabled: boolean): void;
+    enableInspector(): void;
+    disableInspector(): void;
+    clearInspectorSelection(): void;
+    setInspectorSelectionMode(mode: import("../types").MiniAppInspectorSelectionMode): void;
+    getInspectorSceneTree(): Promise<import("../types").MiniAppSceneTreeSnapshot>;
+    selectInspectorByRef(ref: string): Promise<import("../types").VisualSelection | null>;
+    destroy(): void;
+    private createMountTarget;
+}

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

@@ -0,0 +1,2 @@
+export * from "./iframe";
+export * from "./webview";

package/lib/types/renderer/rednote-shell.d.ts

@@ -0,0 +1,73 @@
+import type { MiniAppContentMode, MiniAppSimulatorRoute, MiniAppViewport, NormalizedRednoteDetailSheetOptions, XhsNotePreviewData, XhsProfilePreviewData, XhsWidgetCoverData } from "../types";
+/** RednoteShellMount 所需的最小上下文（由渲染器从 RendererAdapterContext 透传） */
+export interface RednoteShellContext {
+    contentMode: MiniAppContentMode;
+    notePreview: XhsNotePreviewData;
+    profilePreview?: XhsProfilePreviewData;
+    /** 小工具封面：笔记尾卡 + 个人页卡片两处生效 */
+    widgetCover?: XhsWidgetCoverData;
+    rednoteDetail: NormalizedRednoteDetailSheetOptions;
+    viewport: MiniAppViewport;
+    /** 壳层内容收起回调 */
+    onContentClose?: () => void;
+    /** 壳层内容重新唤起回调 */
+    onContentOpen?: () => void;
+    /** 请求唤起内容前的准入检查；返回 false 时保持在笔记页。 */
+    onContentOpenRequest?: () => boolean;
+    /**
+     * 壳层路由变化：note/profile（头像 / 返回点击）、minitool（卡片点击 / sheet 唤起）、
+     * "back"（sheet 收起，由上层回落到当前活动页）。
+     */
+    onRouteChange?: (to: MiniAppSimulatorRoute | "back") => void;
+}
+/** 一次加载的模式行为描述 */
+export interface RednoteLoadBehavior {
+    /** 是否跳过内容载体加载（无 url 占位） */
+    skipContent: boolean;
+    /** 半屏占位/真实内容切换；undefined 表示无需设置 */
+    hasAppUrl?: boolean;
+}
+/**
+ * RednoteShellMount —— renderer 无关的 rednote 外壳挂载/数据同步控制器。
+ *
+ * 负责：注册 Web Component、挂 detail 外壳（half / fullscreen 共用）、提供内容载体挂载点、
+ * 同步 notePreview/sheetOptions、setHasAppUrl/光标隐藏、解析 load 模式行为。
+ *
+ * 不负责：contentRoot/手机壳/缩放（设备外壳由各渲染器自持）、内容载体本身（ContentHost）。
+ */
+export declare class RednoteShellMount {
+    private context;
+    private detailShell;
+    private profileShell;
+    /** 当前活动页（note 笔记页 / profile 个人页）；小工具 sheet 覆盖其上 */
+    private activePage;
+    constructor(context: RednoteShellContext);
+    /**
+     * 在 contentRoot 内挂 detail 外壳（half / fullscreen 共用），返回内容载体挂载点：
+     * 半屏 sheet body（并初始化为占位态）。
+     */
+    mount(contentRoot: HTMLElement): HTMLElement | null;
+    /** 个人页数据：user 仅取 profilePreview 显式注入值（默认保持灰圆占位，不跟随笔记页头像） */
+    private resolveProfilePreview;
+    /** 解析当前 url 的加载行为（无/`about:blank` URL → 占位） */
+    resolveLoad(url: string): RednoteLoadBehavior;
+    /** 增量同步笔记预览数据（不重建外壳） */
+    syncPreviewContext(notePreview: XhsNotePreviewData, rednoteDetail: NormalizedRednoteDetailSheetOptions): void;
+    /** 增量同步个人页数据（不重建外壳） */
+    syncProfilePreview(profilePreview?: XhsProfilePreviewData): void;
+    /** 增量同步小工具封面（笔记尾卡走 notePreview.widgetCover；个人页卡片走 profileShell） */
+    syncWidgetCover(widgetCover?: XhsWidgetCoverData): void;
+    /** 切换活动页：note 笔记页 / profile 个人页 */
+    setActivePage(page: Extract<MiniAppSimulatorRoute, "note" | "profile">): void;
+    /** 当前活动页 */
+    getActivePage(): Extract<MiniAppSimulatorRoute, "note" | "profile">;
+    /** 唤起小工具内容（先过壳层准入检查） */
+    openContent(sheetMode: "half" | "full"): void;
+    /** resize 时同步外壳尺寸相关数据（对齐原 iframe renderer resize 行为） */
+    onResize(viewport: MiniAppViewport): void;
+    setHasAppUrl(hasApp: boolean): void;
+    setSimulatedCursorHidden(hidden: boolean): void;
+    /** 收起小工具内容并等待视觉退场完成，随后才允许宿主展示覆盖提示。 */
+    closeContent(): Promise<void>;
+    destroy(): void;
+}