@skillbuilder/miniapp-simulator 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,59 @@
+import { BridgeProtocol } from "../transport";
+import type { GestureHostPluginLike, MiniAppSimulatorRoute, MiniAppViewport, NormalizedRednoteDetailSheetOptions, RendererAdapter, RendererAdapterContext, XhsNotePreviewData, XhsProfilePreviewData, XhsWidgetCoverData } from "../types";
+import { BaseRendererAdapter } from "./base";
+/**
+ * webview 渲染器：负责设备外壳布局（与 iframe 渲染器同构），通过 RednoteShellMount 挂载
+ * rednote 外壳、通过 WebviewContentHost 承载 Electron `<webview>` 载体。
+ *
+ * 与 iframe 渲染器的差异仅在「内容载体」：webview 为独立 webContents，额外支持
+ * setZoomFactor / DevTools / webContents id / 截屏。
+ */
+export declare class WebviewRendererAdapter extends BaseRendererAdapter implements RendererAdapter {
+    private frame;
+    private overlay;
+    private container;
+    private contentRoot;
+    private rednoteShell;
+    private contentHost;
+    private currentUrl;
+    private desiredZoom;
+    private get transport();
+    bridge: BridgeProtocol | null;
+    private frameToastHost;
+    private detachFramelessShellWindowSync;
+    private viewport;
+    private detachContentPcGuard;
+    private readonly context;
+    private readonly forwardEmit;
+    constructor(context: RendererAdapterContext);
+    mount(container: HTMLElement): Promise<void>;
+    private setupGesture;
+    private attachFramelessShellIfNeeded;
+    private setupBridge;
+    load(url: string): Promise<void>;
+    reload(): Promise<void>;
+    unload(): void;
+    invokeGamePlaytest(method: "manifest" | "snapshot" | "act" | "step" | "reset" | "isAvailable", args?: unknown[]): Promise<unknown>;
+    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;
+    setZoomFactor(factor: number): void;
+    setDevtools(open: boolean): void;
+    setGestureOverlayInteractionEnabled(enabled: boolean): void;
+    isDevtoolsOpen(): boolean;
+    getWebContentsId(): number | null;
+    capture(): Promise<Blob>;
+    showToast(text: string, options?: {
+        duration?: number;
+    }): void;
+    useGesturePlugin(plugin: GestureHostPluginLike): void;
+    removeGesturePlugin(name: string): boolean;
+    hasGesturePlugin(name: string): boolean;
+    listGesturePlugins(): string[];
+    destroy(): void;
+    private createMountTarget;
+}

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

@@ -0,0 +1,31 @@
+/**
+ * 全局运行时 context —— 记录当前模拟器以何种 renderer / 运行环境工作，
+ * 方便宿主与包内各模块识别「web(iframe)」与「electron(webview)」两种模式。
+ *
+ * renderer 由模拟器入口显式传入（见 `createMiniAppSimulator({ renderer })`），
+ * 本模块只负责把它与探测到的运行环境一并存为可全局读取的快照，
+ * 并镜像到 `window.__MINIAPP_SIMULATOR_CONTEXT__` 供 DevTools / 宿主直接查看。
+ */
+import type { MiniAppRendererType } from "../types";
+/** 运行环境：浏览器 web 或 Electron 桌面端 */
+export type SimulatorEnvironment = "web" | "electron";
+export interface SimulatorRuntimeContext {
+    /** 当前激活的渲染器类型（由入口显式传入） */
+    renderer: MiniAppRendererType;
+    /** 探测到的运行环境 */
+    environment: SimulatorEnvironment;
+}
+/**
+ * 探测当前运行环境：
+ *   - `window.process.versions.electron` 存在，或 UA 含 `Electron` → electron
+ *   - 否则 → web
+ */
+export declare function detectEnvironment(): SimulatorEnvironment;
+/**
+ * 写入全局运行时 context（由 simulator 创建时调用），并镜像到 window。
+ */
+export declare function setSimulatorContext(context: SimulatorRuntimeContext): void;
+/**
+ * 读取当前全局运行时 context；尚未创建任何 simulator 时返回 null。
+ */
+export declare function getSimulatorContext(): SimulatorRuntimeContext | null;

package/lib/types/runtime/jsapi-modules/context.d.ts

@@ -0,0 +1,19 @@
+import type { NotePublishResult, NotePublishViewData } from "../../native-ui/note-publish";
+import type { ServiceWorkerHostLike } from "../../sw";
+import type { MiniAppViewport } from "../../types";
+import type { RequestRuntime } from "../request/request-runtime";
+/** Read-only live state shared by simulator JSAPI domain modules. */
+export interface SimulatorJsapiContext {
+    readonly fileSystemHost: ServiceWorkerHostLike | null;
+    readonly fileSystemMountId: string | null;
+    readonly loadedUrl: string;
+    readonly appId: string | undefined;
+    readonly storageScope: string;
+    readonly userDataPath: string | undefined;
+    readonly gateways: Record<string, string> | undefined;
+    readonly businessLine: string | undefined;
+    readonly viewport: MiniAppViewport;
+    readonly requestRuntime: RequestRuntime;
+    readonly overlayRoot: ShadowRoot | HTMLElement;
+    showNotePublish(data: NotePublishViewData): Promise<NotePublishResult> | undefined;
+}

package/lib/types/runtime/jsapi-modules/filesystem.d.ts

@@ -0,0 +1,19 @@
+import type { ServiceWorkerFileSystemArgs, ServiceWorkerFileSystemOperation } from "../../sw";
+import { type MiniAppHostApiHandler } from "../../types";
+import type { SimulatorJsapiContext } from "./context";
+import type { SimulatorJsapiModule } from "./types";
+export type SimulatorFileSystemContext = Pick<SimulatorJsapiContext, "fileSystemHost" | "fileSystemMountId" | "appId">;
+export declare const FILESYSTEM_API_OPERATIONS: {
+    readonly saveFile: "fsSaveFile";
+    readonly writeFile: "fsWriteFile";
+    readonly appendFile: "fsAppendFile";
+    readonly readFile: "fsReadFile";
+    readonly readDir: "fsReadDir";
+    readonly statFile: "fsStatFile";
+    readonly unlink: "fsUnlink";
+    readonly mkdir: "fsMkdir";
+    readonly getFileStorageInfo: "fsGetStorageInfo";
+};
+export declare function createFilesystemJsapiModule(context: SimulatorFileSystemContext): SimulatorJsapiModule;
+export declare function createFilesystemApiHandlers(invoke: (operation: ServiceWorkerFileSystemOperation, args: ServiceWorkerFileSystemArgs) => Promise<unknown>): Record<string, MiniAppHostApiHandler>;
+export declare function invokeSimulatorFileSystem(context: SimulatorFileSystemContext, operation: ServiceWorkerFileSystemOperation, args: ServiceWorkerFileSystemArgs): Promise<unknown>;

package/lib/types/runtime/jsapi-modules/index.d.ts

@@ -0,0 +1,9 @@
+export type { SimulatorJsapiContext } from "./context";
+export { createFilesystemJsapiModule } from "./filesystem";
+export { createInteractionJsapiModule } from "./interaction";
+export { createLocationJsapiModule } from "./location";
+export { createMediaJsapiModule } from "./media";
+export { createNetworkJsapiModule } from "./network";
+export { createSystemJsapiModule } from "./system";
+export { createStorageJsapiModule } from "./storage";
+export { registerSimulatorJsapiModules } from "./types";

package/lib/types/runtime/jsapi-modules/interaction.d.ts

@@ -0,0 +1,4 @@
+import type { SimulatorJsapiContext } from "./context";
+import type { SimulatorJsapiModule } from "./types";
+export type InteractionJsapiModuleContext = Pick<SimulatorJsapiContext, "overlayRoot" | "showNotePublish">;
+export declare function createInteractionJsapiModule(context: InteractionJsapiModuleContext): SimulatorJsapiModule;

package/lib/types/runtime/jsapi-modules/location.d.ts

@@ -0,0 +1,3 @@
+import type { SimulatorJsapiModule } from "./types";
+/** Browser-backed single-shot location APIs. */
+export declare function createLocationJsapiModule(): SimulatorJsapiModule;

package/lib/types/runtime/jsapi-modules/media.d.ts

@@ -0,0 +1,13 @@
+import { type MiniAppHostApiHandler } from "../../types";
+import { type SimulatorFileSystemContext } from "./filesystem";
+import type { SimulatorJsapiModule } from "./types";
+/** The simulator state used by browser media APIs. */
+export interface MediaJsapiModuleContext extends SimulatorFileSystemContext {
+    readonly loadedUrl: string;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly download?: (blob: Blob, filename: string) => void;
+}
+/** Browser media APIs. */
+export declare function createMediaJsapiModule(context: MediaJsapiModuleContext): SimulatorJsapiModule;
+/** Simulates saving an image to the system album by downloading it from the browser. */
+export declare function createSaveImageToPhotosAlbumHandler(context: MediaJsapiModuleContext): MiniAppHostApiHandler;

package/lib/types/runtime/jsapi-modules/network.d.ts

@@ -0,0 +1,3 @@
+import type { SimulatorJsapiContext } from "./context";
+import type { SimulatorJsapiModule } from "./types";
+export declare function createNetworkJsapiModule(context: Pick<SimulatorJsapiContext, "requestRuntime">): SimulatorJsapiModule;

package/lib/types/runtime/jsapi-modules/storage.d.ts

@@ -0,0 +1,26 @@
+import { type MiniAppHostApiHandler } from "../../types";
+import type { SimulatorJsapiContext } from "./context";
+import type { SimulatorJsapiModule } from "./types";
+export declare const STORAGE_LIMIT_BYTES: number;
+export declare const STORAGE_ITEM_LIMIT_BYTES: number;
+export interface SimulatorStorageRecord {
+    scope: string;
+    key: string;
+    data: unknown;
+    sizeBytes: number;
+    encrypted: boolean;
+}
+export interface SimulatorStorageRepository {
+    list(scope: string): Promise<SimulatorStorageRecord[]>;
+    get(scope: string, key: string): Promise<SimulatorStorageRecord | undefined>;
+    put(record: SimulatorStorageRecord): Promise<void>;
+    remove(scope: string, key: string): Promise<void>;
+    clear(scope: string): Promise<void>;
+}
+export interface SimulatorStorageApiOptions {
+    scope: string;
+    repository?: SimulatorStorageRepository;
+}
+export declare function createStorageJsapiModule(context: Pick<SimulatorJsapiContext, "storageScope">): SimulatorJsapiModule;
+/** IndexedDB-backed simulator implementation of the Storage JSAPIs. */
+export declare function createSimulatorStorageApi(options: SimulatorStorageApiOptions): Record<string, MiniAppHostApiHandler>;

package/lib/types/runtime/jsapi-modules/system.d.ts

@@ -0,0 +1,4 @@
+import type { SimulatorJsapiContext } from "./context";
+import type { SimulatorJsapiModule } from "./types";
+export type SystemJsapiModuleContext = Pick<SimulatorJsapiContext, "appId" | "userDataPath" | "gateways" | "businessLine" | "viewport">;
+export declare function createSystemJsapiModule(context: SystemJsapiModuleContext): SimulatorJsapiModule;

package/lib/types/runtime/jsapi-modules/types.d.ts

@@ -0,0 +1,21 @@
+import type { BridgeHandler, BridgeProtocol } from "../../transport/bridge-protocol";
+import type { MiniAppHostApiEntry } from "../../types";
+export type HostOverridePolicy = "allow" | "function-only" | "forbid";
+export interface SimulatorJsapiHandler {
+    handler: BridgeHandler;
+    hostOverride?: HostOverridePolicy;
+}
+/** A cohesive group of simulator-side JSAPI implementations. */
+export interface SimulatorJsapiModule {
+    name: string;
+    handlers: Readonly<Record<string, SimulatorJsapiHandler>>;
+}
+export interface RegisterSimulatorJsapiModulesOptions {
+    hostApiMap: Record<string, MiniAppHostApiEntry>;
+    runHostEntry(entry: MiniAppHostApiEntry, request: Parameters<BridgeHandler>[0]): unknown;
+}
+/**
+ * Registers domain modules in one place and keeps the host override policy uniform.
+ * Modules may not claim the same event, preventing accidental implementation shadowing.
+ */
+export declare function registerSimulatorJsapiModules(bridge: BridgeProtocol, modules: readonly SimulatorJsapiModule[], options: RegisterSimulatorJsapiModulesOptions): void;

package/lib/types/runtime/jsapi-modules/window-info.d.ts

@@ -0,0 +1,43 @@
+/** The only viewport measurements required by the getWindowInfo bridge. */
+interface SimulatorWindowInfoViewport {
+    width: number;
+    height: number;
+}
+interface SimulatorWindowRect {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+}
+interface SimulatorWindowInfo {
+    pixelRatio: number;
+    screenWidth: number;
+    screenHeight: number;
+    windowWidth: number;
+    windowHeight: number;
+    statusBarHeight: number;
+    screenTop: number;
+    safeArea: SimulatorWindowRect;
+    gestureInsets: {
+        left: number;
+        right: number;
+        top: number;
+        bottom: number;
+    };
+    menuButtons: {
+        back: SimulatorWindowRect | null;
+        me: SimulatorWindowRect | null;
+        share: SimulatorWindowRect | null;
+    };
+}
+/**
+ * 构造模拟器侧 `getWindowInfo` 的只读窗口度量。
+ *
+ * 口径：视模拟器设备为「全屏容器」，宽高直接取逻辑视口；状态栏高复用外壳常量，
+ * 底部安全区减掉 home indicator；`menuButtons` 按全屏顶栏 chrome 映射（back/share，
+ * `me` 无对应按钮恒为 null）；侧滑关闭热区只有顶部 grip/status-drag 一档。
+ */
+export declare function buildSimulatorWindowInfo(viewport: SimulatorWindowInfoViewport): SimulatorWindowInfo;
+export {};

package/lib/types/runtime/request/host-request.d.ts

@@ -0,0 +1,13 @@
+import { type MiniAppHostRequest } from "../../types";
+import type { ManagedRequestChunk, ManagedRequestHeaders, ManagedRequestOptions, ManagedRequestResult } from "./request-types";
+export interface HostRequestHooks {
+    signal: AbortSignal;
+    onHeaders(data: ManagedRequestHeaders): void;
+    onChunk(data: ManagedRequestChunk): void;
+}
+type ManagedHostRequestRunner = (options: ManagedRequestOptions, hooks: HostRequestHooks) => Promise<ManagedRequestResult>;
+/** 仅供远程 Runtime 将宿主请求透传到外层页面。 */
+export declare function createManagedHostRequest(runner: ManagedHostRequestRunner): MiniAppHostRequest;
+/** 消费宿主已经适配为统一契约的响应，并生成 simulator 内部请求事件。 */
+export declare function executeHostRequest(request: MiniAppHostRequest, options: ManagedRequestOptions, hooks: HostRequestHooks): Promise<ManagedRequestResult>;
+export {};

package/lib/types/runtime/request/request-manager-frame.d.ts

@@ -0,0 +1,29 @@
+import type { ManagedRequestChunk, ManagedRequestHeaders, ManagedRequestOptions, ManagedRequestResult } from "./request-types";
+export interface IsolatedRequestManagerOptions {
+    mount: HTMLElement;
+    frameUrl?: string;
+    onHeaders(data: ManagedRequestHeaders): void;
+    onChunk(data: ManagedRequestChunk): void;
+}
+/**
+ * 在独立 opaque-origin iframe 中执行公开 request。
+ *
+ * manager iframe 不带 `allow-same-origin`，且 fetch 固定 `credentials: "omit"`，因此不会
+ * 继承宿主 Cookie；它也不复用带严格 connect-src 的渲染 iframe。
+ */
+export declare class IsolatedRequestManager {
+    private readonly iframe;
+    private readonly pending;
+    private readonly onHeaders;
+    private readonly onChunk;
+    private readyResolve;
+    private readonly ready;
+    private destroyed;
+    constructor(options: IsolatedRequestManagerOptions);
+    execute(options: ManagedRequestOptions): Promise<ManagedRequestResult>;
+    abort(taskId: string): boolean;
+    abortAll(): void;
+    destroy(): void;
+    private readonly handleMessage;
+}
+export declare function startIsolatedRequestManagerRuntime(): void;

package/lib/types/runtime/request/request-runtime.d.ts

@@ -0,0 +1,26 @@
+import type { BridgeRequest } from "../../transport/bridge-protocol";
+import { type MiniAppHostRequest } from "../../types";
+import type { ManagedRequestOptions } from "./request-types";
+export interface RequestRuntimeOptions {
+    mount: HTMLElement;
+    requestManagerFrameUrl?: string;
+    getHostRequest(): MiniAppHostRequest | undefined;
+    emit(method: "onHeadersReceivedRequest" | "onEventStream", payload: unknown): void;
+}
+/** request / xhsRequest / abortRequest 的模拟器侧执行层。 */
+export declare class RequestRuntime {
+    private readonly options;
+    private isolatedRequest;
+    private readonly hostRequests;
+    constructor(options: RequestRuntimeOptions);
+    executePublic(req: BridgeRequest): Promise<unknown>;
+    executeInternal(req: BridgeRequest): Promise<unknown>;
+    abort(req: BridgeRequest): {
+        taskId: string;
+    };
+    abortAll(): void;
+    destroy(): void;
+    private getIsolatedRequest;
+}
+export declare function readTaskId(value: unknown): string;
+export declare function readRequestOptions(req: BridgeRequest): ManagedRequestOptions;

package/lib/types/runtime/request/request-types.d.ts

@@ -0,0 +1,26 @@
+export interface ManagedRequestOptions {
+    taskId: string;
+    url: string;
+    method: "GET" | "POST" | "PUT" | "DELETE" | "HEAD" | "OPTIONS";
+    header?: Record<string, string>;
+    data?: unknown;
+    dataType: "json" | "text";
+    responseType: "text";
+    timeout: number;
+    enableChunked: boolean;
+}
+export interface ManagedRequestResult {
+    taskId: string;
+    statusCode: number;
+    data: unknown;
+    header: Record<string, string>;
+}
+export interface ManagedRequestHeaders {
+    taskId: string;
+    statusCode: number;
+    header: Record<string, string>;
+}
+export interface ManagedRequestChunk {
+    taskId: string;
+    chunk: string;
+}

package/lib/types/runtime/request/sse-text-framer.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 只负责 SSE 文本分帧，不解析 event/data/id/retry 字段。
+ *
+ * 网络层的 chunk 边界与 SSE 消息边界无关；这里缓存跨 chunk 的半帧，并在遇到
+ * 空行后返回包含原始换行符的完整 SSE 文本块。
+ */
+export declare class SseTextFramer {
+    private buffer;
+    push(chunk: string): string[];
+    /** SSE 末尾没有空行时属于未完成帧，不向调用方发送。 */
+    finish(): string[];
+    private drain;
+}
+/** 可序列化进隔离 request manager 的无依赖 SSE 分帧器。 */
+export declare function createSseTextFramer(): Pick<SseTextFramer, "push" | "finish">;
+export declare function isEventStreamContentType(contentType: string | undefined | null): boolean;

package/lib/types/seal-config.d.ts

@@ -0,0 +1,134 @@
+/**
+ * 设备能力封印（seal）的运行时配置：以「白名单 allow」语义控制哪些能力放开。
+ *
+ * 设计要点：
+ * - 跨端共用：同一份 IIFE 同时供 PC iframe / iOS WKWebView / Android WebView 注入；通过宿主在 IIFE 之前
+ *   写入 `window.__MINI_APP_SEAL_CONFIG__ = { allow: [...] }` 传配置。
+ * - 字符串字面量值：避免 TS enum 的 runtime 体积；同时让 Swift / Java 可直接使用相同字符串。
+ * - **职责边界**：
+ *   - `Camera` / `Microphone` / `PhotoLibrary` 不属于 seal 直接 forbid 范畴
+ *     （getUserMedia 与 input[type=file] 由宿主层 iframe.allow / WKWebView 权限控制）；
+ *     枚举中保留它们，是为了让 Permissions API stub 与 host 配置在同一份「业务声明」中表达。
+ *   - 其余项与 `seal-runtime/{API}-forbid.ts` 一一对应。
+ *
+ * 注：本文件由 `@skillbuilder/miniapp-simulator` 自维护（源自 `@skillbuilder/miniapp-secure-runtime`）。
+ */
+/** 业务能力枚举（字符串字面量值）。 */
+export declare const MiniAppCapability: {
+    /** 相机：getUserMedia({ video: true })；seal 不直接拦截，由宿主层控制。 */
+    readonly Camera: "camera";
+    /** 麦克风：getUserMedia({ audio: true })；seal 不直接拦截，由宿主层控制。 */
+    readonly Microphone: "microphone";
+    /** 相册 / 文件选择：input[type=file]；seal 不直接拦截，由 sandbox 与 host 配置控制。 */
+    readonly PhotoLibrary: "photo-library";
+    /** 定位：navigator.geolocation。 */
+    readonly Geolocation: "geolocation";
+    /** 剪贴板：navigator.clipboard + execCommand copy/cut/paste。 */
+    readonly Clipboard: "clipboard";
+    /** 蓝牙：navigator.bluetooth。 */
+    readonly Bluetooth: "bluetooth";
+    /** USB：navigator.usb。 */
+    readonly Usb: "usb";
+    /** HID：navigator.hid。 */
+    readonly Hid: "hid";
+    /** 串口：navigator.serial。 */
+    readonly Serial: "serial";
+    /** Generic Sensor 构造器：Accelerometer / Gyroscope / Magnetometer 等。 */
+    readonly GenericSensor: "generic-sensor";
+    /** 设备运动：DeviceMotionEvent + addEventListener('devicemotion')。 */
+    readonly DeviceMotion: "device-motion";
+    /** 设备方向：DeviceOrientationEvent + addEventListener('deviceorientation'/'deviceorientationabsolute')。 */
+    readonly DeviceOrientation: "device-orientation";
+    /** WebRTC 直连：RTCPeerConnection / RTCDataChannel。 */
+    readonly Webrtc: "webrtc";
+    /** 屏幕共享：mediaDevices.getDisplayMedia。 */
+    readonly ScreenShare: "screen-share";
+    /** 媒体设备枚举：mediaDevices.enumerateDevices。 */
+    readonly MediaDeviceEnumeration: "media-device-enumeration";
+    /** 电池：navigator.getBattery。 */
+    readonly Battery: "battery";
+    /** 网络信息：navigator.connection。 */
+    readonly Connection: "connection";
+    /** 持久化存储：navigator.storage.persist。 */
+    readonly PersistentStorage: "persistent-storage";
+    /** 跨域存储访问：document.requestStorageAccess。 */
+    readonly StorageAccess: "storage-access";
+    /** 凭据 / WebAuthn：navigator.credentials。 */
+    readonly Credentials: "credentials";
+    /** Web Locks：navigator.locks。 */
+    readonly Locks: "locks";
+    /** 全屏：Element.requestFullscreen 及前缀实现。 */
+    readonly Fullscreen: "fullscreen";
+    /** input[capture] 直调相机：DOM 扫除 + MutationObserver。 */
+    readonly InputCapture: "input-capture";
+    /** 弹出新窗口：window.open。 */
+    readonly WindowOpen: "window-open";
+    /** 系统输入对话框：window.prompt。 */
+    readonly WindowPrompt: "window-prompt";
+};
+export type MiniAppCapability = (typeof MiniAppCapability)[keyof typeof MiniAppCapability];
+/** 宿主向 seal IIFE 传配置用的全局变量名；必须在 IIFE 之前赋值。 */
+export declare const SEAL_CONFIG_GLOBAL_KEY = "__MINI_APP_SEAL_CONFIG__";
+export interface SealRuntimeConfig {
+    /**
+     * 显式放开的能力列表（白名单）。未列出的能力按 seal 默认策略禁用。
+     * 不传 / 不是数组时，使用 {@link DEFAULT_ALLOW}（保持现行默认：放行 camera / microphone / photo-library）。
+     */
+    allow?: ReadonlyArray<MiniAppCapability>;
+}
+/**
+ * 默认放行的能力 —— 与现行 seal-runtime 行为对齐：
+ * 不主动拦截 getUserMedia 与 input[type=file]，其余 §3 项全部封印。
+ */
+export declare const DEFAULT_ALLOW: ReadonlyArray<MiniAppCapability>;
+/**
+ * 从全局读取宿主注入的 seal 配置。
+ *
+ * @returns 一个 Set，宿主未配置或配置非法时退化为 {@link DEFAULT_ALLOW}。
+ */
+export declare function readSealConfig(): {
+    allow: Set<MiniAppCapability>;
+};
+/**
+ * Permissions API 名称 → 业务 capability 的映射（仅可映射部分；
+ * 不在表中的 permission name 永久 denied，例如 push、notifications 等）。
+ */
+export declare const PERMISSION_TO_CAPABILITY: Readonly<Record<string, MiniAppCapability>>;
+/** 永远拒绝的 permission name（不论 allow 怎样，业务无入口拿到这些能力）。 */
+export declare const ALWAYS_DENIED_PERMISSIONS: ReadonlyArray<string>;
+/**
+ * 能力的受控方：
+ * - `seal`：由本包 IIFE 直接拦截，受 `allow` 白名单控制（不在 allow → 被封印）。
+ * - `host`：seal 不直接拦截，由宿主层控制（PC iframe `allow` / WKWebView 权限 / Android 权限 / sandbox）。
+ *   枚举中保留 host 能力，是为了让宿主配置与 Permissions API stub 在同一份「业务声明」里表达。
+ */
+export type MiniAppCapabilityControlledBy = "seal" | "host";
+/** 单个能力的对外元数据描述。 */
+export interface MiniAppCapabilityDescriptor {
+    /** 枚举值（与 {@link MiniAppCapability} 的字符串字面量一致）。 */
+    value: MiniAppCapability;
+    /** 受控方，决定 `allow` 是否真正影响该能力。 */
+    controlledBy: MiniAppCapabilityControlledBy;
+    /** 人类可读说明（对应底层 Web API）。 */
+    description: string;
+    /** 关联的 Permissions API name（无则为空数组）。 */
+    permissionNames: ReadonlyArray<string>;
+}
+/**
+ * 全量能力元数据表 —— 「支持的能力」唯一事实源。
+ * 顺序与 README 能力表保持一致，便于 UI / 文档直接枚举渲染。
+ */
+export declare const MINI_APP_CAPABILITIES: ReadonlyArray<MiniAppCapabilityDescriptor>;
+/** 全量能力枚举值列表（顺序同 {@link MINI_APP_CAPABILITIES}）。 */
+export declare const ALL_MINI_APP_CAPABILITIES: ReadonlyArray<MiniAppCapability>;
+/** seal IIFE 直接拦截、受 `allow` 控制的能力（白名单实际生效范围）。 */
+export declare const SEAL_CONTROLLED_CAPABILITIES: ReadonlyArray<MiniAppCapability>;
+/** 由宿主层（iframe.allow / WKWebView / sandbox）控制、seal 不直接拦截的能力。 */
+export declare const HOST_CONTROLLED_CAPABILITIES: ReadonlyArray<MiniAppCapability>;
+/** 判断任意值是否为合法的 {@link MiniAppCapability} 枚举取值。 */
+export declare function isMiniAppCapability(value: unknown): value is MiniAppCapability;
+/**
+ * 清洗外部传入的 allow 列表：剔除非枚举项并去重，得到稳定可用的白名单。
+ * 用于宿主把「可能不可信 / 含历史拼写」的配置归一化后再交给 IIFE / snippet。
+ */
+export declare function sanitizeCapabilityList(input: ReadonlyArray<unknown> | null | undefined): MiniAppCapability[];

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

@@ -0,0 +1,9 @@
+/**
+ * SW 渲染方式（`renderer: "iframe-service-worker"`）子系统入口。
+ */
+export { ServiceWorkerHost, type ServiceWorkerHostLike, type ServiceWorkerMountInput, isServiceWorkerHostSupported, } from "./service-worker-host";
+export type { ServiceWorkerFileSystemArgs, ServiceWorkerFileSystemOperation } from "./protocol";
+export { parseRawZip, parseRawFiles, type RawParseResult } from "./parse-raw";
+export { buildSwInjectionPayload, type SwInjectionPayload } from "./served-entry";
+export { ServiceWorkerContentHost } from "./service-worker-content-host";
+export { ServiceWorkerRendererAdapter } from "./service-worker-renderer";

package/lib/types/sw/parse-raw.d.ts

@@ -0,0 +1,34 @@
+/**
+ * SW 模式原始解压 —— 把 zip / 文件表解析为原始文件表（路径 → 原始字节 + 入口 HTML），
+ * 供 Service Worker 当虚拟服务器按真实路径直供，相对路径 / ESM / fetch 原生可用。
+ *
+ * `loadZip` / `loadFiles` 的包解析入口。
+ */
+import type { MiniAppFileMap, MiniAppLoadZipJsZip, MiniAppLoadZipSource, MiniAppPackageLimits } from "../types";
+export declare const DEFAULT_MINIAPP_PACKAGE_LIMITS: MiniAppPackageLimits;
+export interface RawParseResult {
+    /** 入口文件包内路径（已归一化）。 */
+    entryPath: string;
+    /** 入口 HTML 原始文本（尚未注入 head）。 */
+    entryHtml: string;
+    /** 除入口外的全部文件：路径 → 原始字节（可 transfer 给 SW）。 */
+    rawFiles: Record<string, ArrayBuffer>;
+    /** 文件清单（供 loadZip/loadFiles meta 复用）。 */
+    files: Array<{
+        path: string;
+        size: number;
+    }>;
+}
+type PackageLimitInput = Partial<MiniAppPackageLimits> | false | undefined;
+/** 解析 zip → 原始文件表（SW 模式）。 */
+export declare function parseRawZip(source: MiniAppLoadZipSource, options?: {
+    jszip?: MiniAppLoadZipJsZip;
+    entry?: string;
+    limits?: PackageLimitInput;
+}): Promise<RawParseResult>;
+/** 解析「目录文件表」→ 原始文件表（SW 模式）。 */
+export declare function parseRawFiles(fileMap: MiniAppFileMap, options?: {
+    entry?: string;
+    limits?: PackageLimitInput;
+}): RawParseResult;
+export {};

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

@@ -0,0 +1,19 @@
+/** Runtime 与 Service Worker 随同一 release 发布，协议版本必须精确一致。 */
+export declare const SERVICE_WORKER_PROTOCOL_VERSION = 5;
+/** 资源 SW 重启后，向持有包快照的可信宿主请求恢复 Worker 挂载。 */
+export declare const SW_WORKER_MOUNT_RECOVERY = "miniapp:restore-worker-mount";
+/** 当前 Service Worker 提供的文件系统操作。 */
+export declare const SW_FS_OPS: readonly ["fsWriteTempFile", "fsSaveFile", "fsWriteFile", "fsAppendFile", "fsReadFile", "fsReadDir", "fsStatFile", "fsUnlink", "fsMkdir", "fsGetStorageInfo"];
+export type ServiceWorkerFileSystemOperation = (typeof SW_FS_OPS)[number];
+export interface ServiceWorkerFileSystemArgs {
+    fsScope?: string;
+    tempFilePath?: unknown;
+    filePath?: unknown;
+    dirPath?: unknown;
+    data?: unknown;
+    mime?: unknown;
+    encoding?: unknown;
+    position?: unknown;
+    length?: unknown;
+    recursive?: unknown;
+}

package/lib/types/sw/served-entry.d.ts

@@ -0,0 +1,9 @@
+import type { InjectionRegistry } from "../injection/registry";
+import type { NormalizedMiniAppSimulatorOptions } from "../types";
+export interface SwInjectionPayload {
+    /** 注入到 `<head>` 的片段（meta + `<style>` + 带 nonce 的 `<script>`）。 */
+    head: string;
+    /** SW 响应头下发的 CSP。 */
+    csp: string;
+}
+export declare function buildSwInjectionPayload(options: NormalizedMiniAppSimulatorOptions, injection: InjectionRegistry, appUrl: string, rawHtml: string, extraOrigins?: string[], frameAncestors?: string[], userDataPath?: string, gateways?: Record<string, string>, businessLine?: string, workerGuard?: import("../worker/adapters/protocol").WorkerGuardConfig): Promise<SwInjectionPayload>;

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

@@ -0,0 +1,11 @@
+import { IframeContentHost } from "../renderer/content-host/iframe-content-host";
+/**
+ * SW 模式 iframe 载体：复用 IframeContentHost 的全部能力（gesture / inspector /
+ * transport / onload→markReady），仅一处差异：
+ *
+ * SW 直供的「同源虚拟 URL」在 load 前先恢复 SW 注册与内存挂载（壳层收起后再唤起场景），
+ * 其余加载逻辑（`iframe.src = 虚拟URL`）复用父类。head 注入已由 SW 在响应中完成。
+ */
+export declare class ServiceWorkerContentHost extends IframeContentHost {
+    load(url: string): Promise<void>;
+}