@skillbuilder/miniapp-simulator 0.0.0-stage → 0.2.1

package/lib/types/sw/service-worker-host.d.ts

@@ -0,0 +1,74 @@
+/**
+ * ServiceWorkerHost —— `renderer: "iframe-service-worker"` 的宿主侧管理器。
+ *
+ * 负责：注册 SW（按 scope 单例幂等）、把解压后的文件表 MOUNT 给 SW、生成可直连的
+ * 同源虚拟 URL、UNMOUNT 回收。仅依赖浏览器 API（无 Node 依赖，可进 UMD 构建）。
+ */
+import { type ServiceWorkerFileSystemArgs, type ServiceWorkerFileSystemOperation } from "./protocol";
+/** 是否具备启用 SW 模式的运行环境（API 可用 + 安全上下文）。 */
+export declare function isServiceWorkerHostSupported(): boolean;
+export interface ServiceWorkerMountInput {
+    worker?: import("../worker/adapters/package-policy").WorkerMountPolicy;
+    id: string;
+    /** 入口文件包内路径（如 `index.html`），用于生成虚拟 URL。 */
+    entryPath: string;
+    /** 包内全部文件：路径 → 原始字节（会被 transfer 给 SW，调用后不可再用）。 */
+    rawFiles: Record<string, ArrayBuffer>;
+    /** 注入到 HTML `<head>` 的片段（SW 在返回页面时改写写入）。 */
+    injectHead: string;
+    /** CSP 请求白名单（SW 作为响应头下发）。 */
+    csp: string;
+    /** 可选：远程回源基址（入口目录 URL）。传入即为远程代理实例，未挂载子资源回源到此（远程需开 CORS）。 */
+    remoteBase?: string;
+    /** 可选：稳定存储桶身份（= appId）。传入则 writeTempFile 落 IDB 持久化、返回跨会话可读 URL。 */
+    fsScope?: string;
+}
+/** simulator 使用的 SW 宿主最小接口。 */
+export interface ServiceWorkerHostLike {
+    readonly scope: string;
+    fileUrl(fsScope: string, path: string): string;
+    mount(input: ServiceWorkerMountInput): Promise<string>;
+    restoreMount(id: string): Promise<void>;
+    fsInvoke(id: string, op: ServiceWorkerFileSystemOperation, args?: ServiceWorkerFileSystemArgs): Promise<unknown>;
+    unmount(id: string): void;
+}
+export declare class ServiceWorkerHost {
+    private sw;
+    readonly scope: string;
+    private readonly mountTimeout;
+    private registration;
+    private readonly scriptUrl;
+    private static readonly instances;
+    /** 当前 host 已 MOUNT 的 payload 快照；SW 被外部注销/重启后用于重新挂载。 */
+    private readonly mountSnapshots;
+    private supportedFsOps;
+    private constructor();
+    /** 生成与 SW `_xhsfile_` fetch 命名空间完全一致的同源文件 URL。 */
+    fileUrl(fsScope: string, path: string): string;
+    /** 单例获取（固定 scope 幂等注册并等待 SW 激活）。 */
+    static acquire(scriptUrl: string, mountTimeout?: number, scope?: string): Promise<ServiceWorkerHost>;
+    private static create;
+    /**
+     * 挂载一个预览实例，返回可直连的同源虚拟 URL（`<scope><id>/<entryPath>`）。
+     * SW 在返回 HTML 时按 `injectHead` 改写 `<head>`、按 `csp` 下发响应头。
+     */
+    mount(input: ServiceWorkerMountInput): Promise<string>;
+    /** 重新挂载已知实例：用于 iframe 被卸载后再次加载虚拟 URL 前恢复 SW 代理。 */
+    restoreMount(id: string): Promise<void>;
+    /**
+     * 文件系统调用（host→SW）：按 `op` 分派并返回 op 结果。
+     */
+    fsInvoke(id: string, op: ServiceWorkerFileSystemOperation, args?: ServiceWorkerFileSystemArgs): Promise<unknown>;
+    private sendFsRequest;
+    unmount(id: string): void;
+    private postWithAck;
+    private sendMount;
+    /**
+     * MOUNT 前自检：确保仍持有【我们自己】的、可用的 SW。
+     * - 注册仍在 → 刷新 this.sw / this.registration 到当前活跃 worker。
+     * - 注册被外部注销 → 重新注册并等待激活，刷新引用。
+     */
+    private ensureActiveWorker;
+    /** 校验注册确属我们的实例（scope 精确匹配），排除宿主根 scope SW 的最长前缀回退命中。 */
+    private isOurRegistration;
+}

package/lib/types/sw/service-worker-renderer.d.ts

@@ -0,0 +1,10 @@
+import type { ContentHostContext } from "../renderer/content-host/types";
+import { IframeRendererAdapter } from "../renderer/iframe";
+import { ServiceWorkerContentHost } from "./service-worker-content-host";
+/**
+ * SW 模式渲染器：完全复用 IframeRendererAdapter（设备外壳 / rednote 壳层 / 手势 /
+ * 选取 / 权限弹窗），仅把内容载体替换为 {@link ServiceWorkerContentHost}。
+ */
+export declare class ServiceWorkerRendererAdapter extends IframeRendererAdapter {
+    protected createContentHost(ctx: ContentHostContext): ServiceWorkerContentHost;
+}

package/lib/types/sw/worker/fs-codec.d.ts

@@ -0,0 +1,23 @@
+/**
+ * fs-codec —— data: URI 解码 + MIME 白名单（**零依赖纯逻辑**，仅用 `atob`/`Uint8Array`）。
+ *
+ * 文件系统层通用工具，供各 op 复用（当前 write，未来 read 等），非某个 jsapi 专属。
+ * 只接受 base64 `data:` URI，MIME 必须在白名单内；其余（裸 base64 / http(s) / 不支持 MIME /
+ * 坏 base64）一律拒绝。白名单对齐端上「小工具本地文件能力」一期（图片 + 视频）。
+ */
+/** 文件系统支持的 MIME → 扩展名白名单（一期图片 + 视频）。 */
+export declare const SW_MIME_EXT: Record<string, string>;
+export type DecodeErrorCode = "ERR_INVALID_ARGS" | "ERR_UNSUPPORTED_MIME";
+export interface DecodeOk {
+    bytes: ArrayBuffer;
+    mime: string;
+    ext: string;
+}
+export interface DecodeErr {
+    error: string;
+    code: DecodeErrorCode;
+}
+/** 通过文件魔数识别可由 DOM 直连渲染的媒体类型。 */
+export declare function sniffMediaMime(buffer: ArrayBuffer): string | undefined;
+/** 解析并解码 `data:<mime>;base64,<body>`。成功返回字节+mime+ext；失败返回错误码。 */
+export declare function decodeDataUri(input: unknown): DecodeOk | DecodeErr;

package/lib/types/sw/worker/fs-ops.d.ts

@@ -0,0 +1,22 @@
+/** Runtime file system operations and `_xhsfile_` URL serving. */
+import type { ServiceWorkerFileSystemArgs, ServiceWorkerFileSystemOperation } from "../protocol";
+export declare const FS_USR_LIMIT_BYTES: number;
+export declare const FS_WRITE_CHUNK_LIMIT_BYTES: number;
+export declare const FS_READ_CHUNK_LIMIT_BYTES: number;
+export declare const FS_SESSION_WRITE_LIMIT_BYTES: number;
+export declare const FS_MAX_DEPTH = 4;
+export declare const FS_PATH_MAX_BYTES = 255;
+export interface FsMessage extends ServiceWorkerFileSystemArgs {
+    op: ServiceWorkerFileSystemOperation;
+    id: string;
+    reqId: string;
+}
+export declare function releaseFsSession(id: string): void;
+export declare function handleFsOp(data: FsMessage): Promise<Record<string, unknown>>;
+/** Parse a simulator runtime-file URL for the fetch interception path. */
+export declare function parseXhsFileUrl(rawUrl: string): {
+    scope: string;
+    path: string;
+} | null;
+/** Serve media files to img/video/CSS; non-media bytes intentionally return 404. */
+export declare function serveXhsFile(scope: string, path: string): Promise<Response>;

package/lib/types/sw/worker/fs-store.d.ts

@@ -0,0 +1,29 @@
+/** IndexedDB-backed runtime file store used by the simulator Service Worker. */
+export interface StoredFile {
+    path: string;
+    bytes: ArrayBuffer;
+    mime: string;
+    isDir: boolean;
+    lastModified: number;
+}
+export interface StoredEntry {
+    path: string;
+    mime: string;
+    size: number;
+    isDir: boolean;
+    lastModified: number;
+}
+/** 写入或覆盖普通文件。 */
+export declare function idbPut(scope: string, path: string, bytes: ArrayBuffer, mime?: string): Promise<void>;
+/** 创建目录记录。 */
+export declare function idbPutDirectory(scope: string, path: string): Promise<void>;
+/** 读取单个条目；不存在返回 null。 */
+export declare function idbGet(scope: string, path: string): Promise<StoredFile | null>;
+/** 列出 scope 下的全部文件与目录元信息。 */
+export declare function idbList(scope: string): Promise<StoredEntry[]>;
+/** 删除单个条目。 */
+export declare function idbDelete(scope: string, path: string): Promise<void>;
+/** 在同一个事务中移动文件，目标由调用方保证不存在。 */
+export declare function idbMove(scope: string, sourcePath: string, targetPath: string, source: StoredFile): Promise<void>;
+/** 删除某个 scope 下的全部条目。 */
+export declare function idbDeleteScope(scope: string): Promise<void>;

package/lib/types/sw/worker/globals.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Service Worker 全局最小类型 + `sw` 句柄。
+ *
+ * 用最小本地类型描述 SW 全局，避免与项目 DOM lib 的全局类型冲突（无需引入 `webworker` lib）。
+ * 仅 worker 运行时内部使用。
+ */
+export interface SwExtendableEvent {
+    waitUntil(promise: Promise<unknown>): void;
+}
+export interface SwMessageEvent {
+    data: unknown;
+    ports: ReadonlyArray<MessagePort>;
+    source?: SwClient | MessagePort | null;
+    /** ExtendableMessageEvent.waitUntil：异步 op（FS）期间保活 SW。 */
+    waitUntil?(promise: Promise<unknown>): void;
+}
+export interface SwFetchEvent {
+    request: Request;
+    /** 发起该请求的文档/worker client id（子资源请求时指向所属文档）。 */
+    clientId: string;
+    /** 导航请求新建 client 的 id（文档自身导航时用）。 */
+    resultingClientId: string;
+    respondWith(response: Response | Promise<Response>): void;
+}
+export interface SwClient {
+    id: string;
+    url: string;
+    postMessage(message: unknown, transfer: Transferable[]): void;
+}
+export interface SwClients {
+    claim(): Promise<void>;
+    get(id: string): Promise<SwClient | undefined>;
+    matchAll(options?: {
+        type?: "window";
+        includeUncontrolled?: boolean;
+    }): Promise<SwClient[]>;
+}
+export interface SwGlobalScope {
+    skipWaiting(): Promise<void>;
+    clients: SwClients;
+    /** 本 SW 注册 scope（完整 URL，如 `https://origin/miniapp-simulator/`），用于拼同源虚拟 URL。 */
+    registration: {
+        scope: string;
+    };
+    addEventListener(type: "install", listener: (event: SwExtendableEvent) => void): void;
+    addEventListener(type: "activate", listener: (event: SwExtendableEvent) => void): void;
+    addEventListener(type: "message", listener: (event: SwMessageEvent) => void): void;
+    addEventListener(type: "fetch", listener: (event: SwFetchEvent) => void): void;
+}
+export declare const sw: SwGlobalScope;

package/lib/types/sw/worker/main.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Service Worker 入口 —— 注册 install/activate/message/fetch 四个监听，分派给 `./` 内逻辑模块。
+ *
+ * Runtime 与 SW 从同一 release manifest 成对加载，消息协议随 release 一起演进。
+ */
+export {};

package/lib/types/sw/worker/mime.d.ts

@@ -0,0 +1,2 @@
+/** 包内文件扩展名 → Content-Type 映射（文本 / 二进制），供 SW 直供时打 MIME。 */
+export declare function mimeForPath(path: string): string;

package/lib/types/sw/worker/mount-store.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 挂载表 —— id → 已挂载小工具实例。多预览实例 / 多 iframe 共用一个 SW，按 id 前缀隔离。
+ * 负责 MOUNT/UNMOUNT 的存储，以及请求路径 → 实例的两级归属查找（`/<id>/` 标记 + clientId 反查）。
+ */
+import type { WorkerMountPolicy } from "../../worker/adapters/package-policy";
+export interface MountedFile {
+    bytes: ArrayBuffer;
+    mime: string;
+}
+export interface MountedApp {
+    worker?: WorkerMountPolicy;
+    /** 以包内文件路径为键缓存原始字节及独立 CSP 响应。 */
+    workerResponses: Map<string, Response>;
+    files: Map<string, MountedFile>;
+    /** 注入到 HTML `<head>` 的片段（seal/jsapi/render-done 等）。 */
+    injectHead: string;
+    /** 作为响应头下发的 CSP（请求白名单）。 */
+    csp: string;
+    /** 远程回源基址（入口目录 URL）。非空＝远程代理实例：子资源未命中回源到此；空＝纯离线包，未命中 404。 */
+    remoteBase: string;
+    /** 稳定存储桶身份（= host 传入的 appId）；空串时由调用方回退到 mount id。 */
+    fsScope: string;
+    /** 发起 MOUNT 的页面 Client；页面异常退出时用于回收没有机会发送 UNMOUNT 的孤儿挂载。 */
+    ownerClientId: string;
+}
+export declare const STORE: Map<string, MountedApp>;
+export interface MountInput {
+    worker?: WorkerMountPolicy;
+    id: string;
+    files: Record<string, ArrayBuffer>;
+    injectHead: string;
+    csp: string;
+    remoteBase?: string;
+    fsScope?: string;
+    ownerClientId?: string;
+}
+/** 挂载一个实例，返回文件数。 */
+export declare function mountApp(input: MountInput): number;
+export declare function unmountApp(id: string): void;
+/** 清理所属页面已不存在的挂载；无 owner 的旧协议挂载保留，避免误删仍在运行的实例。 */
+export declare function pruneOrphanedApps(activeClientIds: ReadonlySet<string>): number;
+/** 把请求 URL 解析为「命中的挂载实例 + 包内文件路径」。仅按 pathname 匹配，忽略 query。 */
+export declare function resolveRequest(rawUrl: string): {
+    app: MountedApp;
+    filePath: string;
+} | null;
+/** 按 client 文档 URL 反查其所属的已挂载实例（url 含 `/<id>/`）。 */
+export declare function findAppByClientUrl(clientUrl: string): MountedApp | null;

package/lib/types/sw/worker/paths.d.ts

@@ -0,0 +1,4 @@
+/** `decodeURIComponent` 的安全封装：畸形百分号编码（如 `%ZZ`）不抛 URIError，返回 null。 */
+export declare function safeDecode(input: string): string | null;
+/** 归一化包内路径：统一正斜杠、去 `./` 与前导 `/`、拒绝 `..` 穿越。非法返回空串。 */
+export declare function normalizePath(input: string): string;

package/lib/types/sw/worker/serve.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 响应构造 —— 把命中的包内文件落成 Response。
+ *   · serveDirect：`/<id>/` 标记命中直供；远程代理实例未命中则回源。
+ *   · serveByClient：根绝对路径 `/assets/x`（无标记）按 clientId 反查归属实例再供/回源/透传。
+ *   · serveBytes：裸字节 → Response（供运行期文件 `_xhsfile_` 复用）。
+ */
+import { type MountedApp } from "./mount-store";
+/** 命中实例取本地文件；远程代理实例未命中则按相对路径回源，纯离线包未命中 404。 */
+export declare function serveDirect(app: MountedApp, filePath: string, request: Request): Response | Promise<Response>;
+/** 根绝对路径回退：按 clientId 反查归属实例，命中文件则供，有 remoteBase 则回源，否则透传。 */
+export declare function serveByClient(clientId: string, request: Request): Promise<Response>;
+/** 裸字节 → Response（no-store）。供包内二进制文件与运行期 `_xhsfile_` 文件共用。 */
+export declare function serveBytes(bytes: ArrayBuffer, mime: string): Response;

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

@@ -0,0 +1,14 @@
+import type { MiniAppApmRegion } from "../types";
+/** APM 自定义打点的 measurement_name，所有 tracker 上报统一使用 */
+export declare const APM_MEASUREMENT_NAME = "miniapp_simulator_event";
+/** APM 应用标识（context_artifactName），后端按此归类本 SDK 的上报 */
+export declare const APM_ARTIFACT_NAME = "skillbuilder-miniapp";
+/** 按 region + 环境分的 APM xray 上报端点；可由 tracker.endpoint 覆盖 */
+export declare const APM_ENDPOINT: Record<MiniAppApmRegion, {
+    production: string;
+    development: string;
+}>;
+/** 批量上报：缓冲达到此条数立即发送 */
+export declare const APM_BATCH_MAX = 10;
+/** 批量上报：缓冲未满时最多等待此毫秒后发送 */
+export declare const APM_BATCH_FLUSH_MS = 10000;

package/lib/types/tracker/default-tracker.d.ts

@@ -0,0 +1,19 @@
+import type { MiniAppApmRegion, MiniAppTrackerEvent } from "../types";
+/** 默认 Tracker 的上报方法集合 */
+export interface DefaultTracker {
+    sendCustomPoint(event: MiniAppTrackerEvent): void;
+    /** 立即发送缓冲中的所有打点 */
+    flush(): void;
+}
+export interface DefaultTrackerConfig {
+    /** xray 上报端点 URL */
+    endpoint: string;
+    /** 上报地域，注入 context_accountGeographicZone */
+    region: MiniAppApmRegion;
+    /** 异步获取当前用户 ID（来自 tracker 选项的 `getUserInfo`），注入 context_userId */
+    resolveUserId: () => Promise<string>;
+    /** 打印到 console 而非真正上报；仅显式传 true 时开启。 */
+    debug?: boolean;
+}
+/** 创建默认 Tracker：自定义点位缓冲后批量 POST 到 APM 端点 */
+export declare function createDefaultTracker(config: DefaultTrackerConfig): DefaultTracker;

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

@@ -0,0 +1,70 @@
+import type { EventBus } from "../event-bus";
+import type { BridgeInvokeResult } from "../transport";
+import type { MiniAppTrackerInput, MiniAppTrackerOptions } from "../types";
+/** 解析上报端点：`endpoint` 优先，否则只按当前域名选测试/正式端点。 */
+export declare function resolveTrackerEndpoint(input: MiniAppTrackerOptions): string;
+export declare class MiniAppTracker {
+    private readonly resolveContext?;
+    private readonly send;
+    private readonly flush;
+    private readonly unsubscribers;
+    /** 公共字段，init 时设置，后续所有打点自动注入 */
+    private common;
+    constructor(input: MiniAppTrackerInput, eventBus: EventBus, resolveUserId?: () => Promise<string>, resolveContext?: (() => Record<string, string | number | undefined>) | undefined);
+    /** 页面隐藏时立即冲刷缓冲，避免关闭前丢数据 */
+    private bindFlushOnHidden;
+    private bindEvents;
+    /** 初始化公共字段并上报 simulator_init */
+    trackInit(params: {
+        renderer: string;
+        contentMode: string;
+        appUrl: string;
+        sdkVersion: string;
+    }): void;
+    /** 上报 reload 事件 */
+    trackReload(url: string): void;
+    /** srcdoc 注入完成 */
+    trackInjectDone(params: {
+        url: string;
+        injected: boolean;
+        duration: number;
+    }): void;
+    /** 权限弹窗操作结果 */
+    trackPermissionResult(params: {
+        type: string;
+        result: string;
+    }): void;
+    /** zip/files 解析完成 */
+    trackParseDone(params: {
+        type: string;
+        duration: number;
+        count: number;
+        entry?: string;
+    }): void;
+    /** SW 注册 + 激活结果（renderer: iframe-service-worker）；scope 复用 url 字段 */
+    trackSwRegister(params: {
+        result: "success" | "fail";
+        duration: number;
+        url?: string;
+        message?: string;
+    }): void;
+    /** SW MOUNT（文件表挂载 + ACK）结果 */
+    trackSwMount(params: {
+        result: "success" | "fail";
+        duration: number;
+        count?: number;
+        entry?: string;
+        message?: string;
+    }): void;
+    /** 远程加载内部阶段；stage 保持低基数枚举，扩展字段只承载耗时与结果。 */
+    trackLoadStage(stage: string, params: Record<string, string | number | boolean | undefined>): void;
+    /** bridge 调用完成回调 */
+    handleBridgeInvoke(result: BridgeInvokeResult): void;
+    /** 发送打点：自动合入公共字段 */
+    private track;
+    destroy(): void;
+}
+/**
+ * 判断 tracker input 是否启用。
+ */
+export declare function isTrackerEnabled(input?: MiniAppTrackerInput): input is MiniAppTrackerOptions;

package/lib/types/transport/bridge-protocol.d.ts

@@ -0,0 +1,78 @@
+import type { Transport } from "./types";
+/**
+ * BridgeProtocol —— Simulator 宿主侧 jsapi 协议解析器（介质无关）
+ *
+ * 本类只面向 {@link Transport} 接口编程，与 iframe / webview 介质完全解耦。
+ *
+ * 职责：
+ *   1. 监听 transport 来的消息，识别 `xhs:invoke` 调用并路由到对应 handler
+ *   2. 把 handler 返回值包装成 `{ code: 0, data }` 或 `{ code, msg }`，
+ *      通过 `transport.post(callbackMessage)` 异步回写
+ *   3. 主动推送事件 `emit(method, payload)` → `xhs:event` 消息
+ *   4. 处理模拟器通道 `ready` 心跳（仅 debug 时记录）
+ *
+ * 详见：design/mini-app/mini-app-simulator-refactor-design.md §6
+ */
+/** Handler 入参：jsapi 调用解析后的协议字段 */
+export interface BridgeRequest {
+    /** jsapi event 名（如 `share` / `xhsRequest`） */
+    event: string;
+    /** sdk 传给 invoke 的业务参数（不含 success/fail/complete） */
+    message: Record<string, unknown>;
+    /** callbackId，可用于自定义异步回调时序 */
+    callbackId: string;
+}
+/**
+ * Handler 返回的"业务数据"会被 BridgeProtocol 包装成 `{ code: 0, data }` 回写。
+ * 抛错（同步或 reject）将被视为失败，包装成 `{ code, msg }`。
+ */
+export type BridgeHandler = (request: BridgeRequest) => unknown | Promise<unknown>;
+/** bridge 调用结果回调（Tracker 用） */
+export interface BridgeInvokeResult {
+    event: string;
+    success: boolean;
+    duration: number;
+    error?: string;
+}
+export interface BridgeProtocolOptions {
+    /** 默认延迟（毫秒），模拟端到端往返；默认 60 */
+    defaultDelay?: number;
+    /** 调试日志开关 */
+    debug?: boolean;
+    /** bridge 调用完成回调（成功/失败），供 Tracker 上报 */
+    onInvoke?: (result: BridgeInvokeResult) => void;
+}
+export declare class BridgeProtocol {
+    private readonly transport;
+    private readonly handlers;
+    private readonly defaultDelay;
+    private fallbackHandler;
+    private readonly debug;
+    private readonly onInvoke?;
+    private readonly unsubscribe;
+    private destroyed;
+    constructor(transport: Transport, options?: BridgeProtocolOptions);
+    /** Simulator 内部设置未注册事件的最终路由。 */
+    setFallbackHandler(handler: BridgeHandler): void;
+    /** 注册（或覆盖）单个 event 的 handler，返回 unsubscribe */
+    handle(event: string, handler: BridgeHandler): () => void;
+    /**
+     * 批量注册 handler map。常用于 `options.hostApi` 入口。
+     * 同名 event 会覆盖之前注册的 handler。
+     */
+    register(map: Record<string, BridgeHandler>): void;
+    /** 是否已注册 handler */
+    has(event: string): boolean;
+    /** 移除单个 event 的 handler */
+    remove(event: string): void;
+    /** 清空所有精确 handler（保留内部 fallbackHandler） */
+    clear(): void;
+    /**
+     * 主动向小应用推送事件（触发 jsapi 的 `subscribe(method, ...)` 监听）。
+     * payload 形态符合 `{ type: "events", method, payload }`，本方法做自动包装。
+     */
+    emit(method: string, payload?: unknown): void;
+    destroy(): void;
+    private readonly handleMessage;
+    private dispatch;
+}

package/lib/types/transport/iframe-transport.d.ts

@@ -0,0 +1,39 @@
+import type { Transport, TransportMessage } from "./types";
+/**
+ * IframeTransport —— iframe 介质的 Transport 实现。
+ *
+ * 数据流：
+ *   宿主 → 小应用：  this.iframe.contentWindow.postMessage(msg, iframeOrigin)
+ *   小应用 → 宿主：  校验 source + origin 后分发
+ *
+ * 设计说明：
+ * - 跨站 OOPIF 模式下必须只接收当前 iframe 的消息，并使用精确 targetOrigin，避免其它
+ *   frame 伪造 bridge 调用。默认 sandbox 含 allow-same-origin，因此 event.origin 可稳定校验。
+ * - `ready` 在 `markReady()` 之前是 pending 状态；renderer 在 `iframe.onload`
+ *   触发后调用 `markReady()`。
+ *
+ * 注：本类**不感知具体业务消息**（jsapi/console/navigation/render-done），
+ * 它只负责字节搬运。业务路由由上层模块完成。
+ */
+export declare class IframeTransport implements Transport {
+    readonly ready: Promise<void>;
+    private readyResolve;
+    private iframe;
+    private readonly handlers;
+    private destroyed;
+    constructor();
+    /**
+     * 将 Transport 绑定到目标 iframe 元素。
+     * 调用之前 `post` 会被静默丢弃。
+     */
+    attach(element: HTMLElement): void;
+    /**
+     * Renderer 在 iframe.onload（或 srcdoc load done）后调用，触发 ready。
+     * 重复调用幂等。
+     */
+    markReady(): void;
+    post(message: TransportMessage): void;
+    onMessage(handler: (msg: TransportMessage) => void): () => void;
+    destroy(): void;
+    private readonly handleMessage;
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Transport 层统一出口（介质相关通道 + 协议）。
+ *
+ * - `Transport / TransportMessage`：介质无关的字节通道接口
+ * - `IframeTransport / WebviewTransport`：两种介质的实现
+ * - `BridgeProtocol / BridgeHandler / BridgeRequest`：jsapi 协议解析器
+ *
+ * Kernel 与 Plugin 内部使用本文件统一导入；不对宿主暴露（不在
+ * [`src/index.ts`](../index.ts) 中 re-export）。
+ */
+export { IframeTransport } from "./iframe-transport";
+export { WebviewTransport, WEBVIEW_IPC_CHANNEL } from "./webview-transport";
+export type { Transport, TransportMessage } from "./types";
+export { BridgeProtocol, type BridgeHandler, type BridgeInvokeResult, type BridgeProtocolOptions, type BridgeRequest, } from "./bridge-protocol";

package/lib/types/transport/jsapi-bridge-messages.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Simulator host ↔ guest JS API bridge message contract.
+ *
+ * This contract belongs to the simulator because it describes its transport,
+ * rather than the client JS API's native bridge contract.
+ */
+export declare const SIMULATOR_JSAPI_MESSAGE_TYPES: {
+    /** guest → host: the simulator bridge is ready */
+    readonly ready: "designable-small-tool:xhs:ready";
+    /** guest → host: an SDK call forwarded through xhsInvoke */
+    readonly invoke: "designable-small-tool:xhs:invoke";
+    /** host → guest: an asynchronous SDK result */
+    readonly invokeCallback: "designable-small-tool:xhs:invoke:callback";
+    /** host → guest: a pushed SDK event */
+    readonly event: "designable-small-tool:xhs:event";
+};
+export type SimulatorJsapiMessageType = (typeof SIMULATOR_JSAPI_MESSAGE_TYPES)[keyof typeof SIMULATOR_JSAPI_MESSAGE_TYPES];
+export interface SimulatorJsapiInvokeMessage {
+    type: typeof SIMULATOR_JSAPI_MESSAGE_TYPES.invoke;
+    raw: string;
+}
+export interface SimulatorJsapiInvokeCallbackMessage {
+    type: typeof SIMULATOR_JSAPI_MESSAGE_TYPES.invokeCallback;
+    callbackId: string;
+    result: unknown;
+}
+export interface SimulatorJsapiEventMessage {
+    type: typeof SIMULATOR_JSAPI_MESSAGE_TYPES.event;
+    payload: unknown;
+}
+export interface SimulatorJsapiReadyMessage {
+    type: typeof SIMULATOR_JSAPI_MESSAGE_TYPES.ready;
+    agent: "designable-small-tool-simulator";
+    timestamp: number;
+}
+export type SimulatorJsapiMessage = SimulatorJsapiReadyMessage | SimulatorJsapiInvokeMessage | SimulatorJsapiInvokeCallbackMessage | SimulatorJsapiEventMessage;

package/lib/types/transport/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Transport —— 字节搬运通道接口（介质相关）
+ *
+ * 本接口由 Renderer 实现：
+ * - IframeTransport：postMessage / window.message
+ * - WebviewTransport：webview.send / ipc-message
+ *
+ * 业务层（BridgeProtocol）只面向本接口编程，不感知介质差异。
+ *
+ * 设计意图见：design/mini-app/mini-app-simulator-refactor-design.md §6
+ */
+/**
+ * 通道载荷格式：仅约定一个 `type` 字符串作为路由依据，其它字段透传。
+ * BridgeProtocol 在其之上叠加 `{ raw, callbackId, result, payload }` 等语义字段。
+ */
+export interface TransportMessage {
+    type: string;
+    [key: string]: unknown;
+}
+/**
+ * Renderer 持有 / Kernel 注入给 BridgeProtocol 的统一通道。
+ */
+export interface Transport {
+    /**
+     * mount + 子文档/子进程通道就绪后 resolve。
+     * - iframe：`iframe.onload` 后
+     * - webview：`dom-ready` 后
+     *
+     * 在 ready 之前 `post(...)` 也允许调用，但实现可选择缓冲到 ready 后发出。
+     */
+    readonly ready: Promise<void>;
+    /**
+     * 将 Transport 绑定到目标 DOM 元素（iframe / webview）。
+     * 由 Renderer 在 mount 阶段调用，Kernel 创建 Transport 后注入。
+     */
+    attach(element: HTMLElement): void;
+    /**
+     * 通知 Transport 通道已就绪（iframe.onload / webview dom-ready）。
+     * 重复调用幂等。
+     */
+    markReady(): void;
+    /** 宿主 → 小应用 */
+    post(message: TransportMessage): void;
+    /** 小应用 → 宿主；返回 unsubscribe */
+    onMessage(handler: (message: TransportMessage) => void): () => void;
+    /** 卸载所有监听，幂等。 */
+    destroy(): void;
+}