@skillbuilder/miniapp-simulator 0.0.0-stage → 0.2.1

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

@@ -0,0 +1,52 @@
+import type { Transport, TransportMessage } from "./types";
+/** webview / preload 之间约定的 IPC 通道名 */
+export declare const WEBVIEW_IPC_CHANNEL: "mas:msg";
+/**
+ * WebviewTransport —— electron `<webview>` 介质的 Transport 实现。
+ *
+ * 数据流：
+ *   宿主（renderer 进程） → 小应用：
+ *     webviewEl.send('mas:msg', message)
+ *       → preload 收到后 dispatch 到 window
+ *
+ *   小应用 → 宿主（renderer 进程）：
+ *     小应用执行 `window.postMessage(message, '*')`
+ *       → preload 监听 window.message → `ipcRenderer.sendToHost('mas:msg', message)`
+ *       → 当前类的 `ipc-message` 监听
+ *
+ * preload 脚本由 Step 5 的 `injection/preload-builder.ts` 产出，
+ * 当前阶段（Step 2）此类仅维护通道协议，与 preload 联调待 Step 5。
+ */
+export declare class WebviewTransport implements Transport {
+    readonly ready: Promise<void>;
+    private readyResolve;
+    private webview;
+    private readonly handlers;
+    private destroyed;
+    /**
+     * dom-ready 之前 `webview.send` 会抛 "The WebView must be attached to the DOM
+     * and the dom-ready event emitted..."。按 Transport 契约（types.ts），ready 前的
+     * post 缓冲到通道就绪后统一 flush，避免 gesture plugin 在 install 阶段（mount 期、
+     * 尚未 dom-ready）同步 send 直接抛错，阻断整个 load()。
+     */
+    private isReady;
+    private readonly pending;
+    constructor();
+    /**
+     * 将 Transport 绑定到目标 webview 元素，并监听 ipc-message / dom-ready。
+     */
+    attach(element: HTMLElement): void;
+    /**
+     * 兜底入口：宿主可显式触发 ready（例如基于 did-finish-load 而非 dom-ready）。
+     * 重复调用幂等。
+     */
+    markReady(): void;
+    post(message: TransportMessage): void;
+    private sendNow;
+    /** 通道就绪：flush 缓冲队列并 resolve ready（dom-ready 事件或宿主显式触发） */
+    private markChannelReady;
+    onMessage(handler: (msg: TransportMessage) => void): () => void;
+    destroy(): void;
+    private readonly handleDomReady;
+    private readonly handleIpcMessage;
+}

package/lib/types/types/events.d.ts

@@ -0,0 +1,130 @@
+import type { ElementSelection, MiniAppElementSelectionChangeEvent, MiniAppInspectorChangeEvent, MiniAppVisualSelectionChangeEvent, VisualSelection } from "./inspector";
+import type { MiniAppContentMode, MiniAppRendererType, MiniAppScreenShotResult, MiniAppSimulatorRoute, MiniAppViewport } from "./options";
+/**
+ * 事件类型（原 types.ts 段落 2）。
+ */
+export type MiniAppEventName = "ready" | "beforeLoad" | "load" | "renderDone" | "error" | "navigation" | "console" | "guestError" | "network" | "performance" | "capture" | "destroy" | "routerChange" | "screenShot" | "elementHovered" | "elementSelected" | "elementSelectionChange" | "visualHovered" | "visualSelected" | "visualSelectionChange" | "inspectorChange";
+export interface MiniAppReadyEvent {
+    renderer: MiniAppRendererType;
+    viewport: MiniAppViewport;
+}
+export interface MiniAppBeforeLoadEvent {
+    /** 即将加载的最终 URL（half / fullscreen 占位时为空串） */
+    url: string;
+    contentMode: MiniAppContentMode;
+    /** 触发来源：load / reload / switch-mode / switch-frame / load-app / load-zip / load-files 等 */
+    source: string;
+}
+export interface MiniAppLoadEvent {
+    url: string;
+    duration: number;
+}
+export interface MiniAppRenderDoneEvent {
+    /** 完成首屏渲染的 URL */
+    url: string;
+    /** 从加载开始到首帧渲染完毕的耗时（ms） */
+    duration: number;
+}
+export interface MiniAppErrorEvent {
+    code: MiniAppErrorCode;
+    message: string;
+    url?: string;
+    cause?: unknown;
+}
+export interface MiniAppNavigationEvent {
+    from: string;
+    to: string;
+    blocked: boolean;
+}
+export interface MiniAppConsoleEvent {
+    level: "debug" | "info" | "warn" | "error" | "log";
+    message: string;
+    /** 来源：`sdk`（框架注入脚本）/ `user`（业务代码） */
+    source: "sdk" | "user";
+    args?: unknown[];
+}
+export interface MiniAppGuestErrorEvent {
+    /** 错误来源：JS / Promise / CSP / fetch / AI SDK。 */
+    type: "error" | "unhandledrejection" | "securitypolicyviolation" | "fetch" | "ai";
+    name: string;
+    message?: string;
+    /** JS：filename:line:col；资源：标签名；fetch */
+    source?: string;
+    /** 出错脚本 / 失败资源 / 请求 URL */
+    url?: string;
+    /** 错误堆栈（JS / Promise / fetch 有） */
+    stack?: string;
+    disposition?: string;
+    effective_directive?: string;
+    violated_directive?: string;
+    blocked_uri?: string;
+    source_file?: string;
+    line_number?: number;
+    column_number?: number;
+    original_policy?: string;
+    code?: number;
+    request_id?: string;
+    model?: string;
+    operation?: "generateText" | "streamText";
+    details?: Record<string, unknown>;
+}
+export interface MiniAppNetworkEvent {
+    url: string;
+    method?: string;
+    status?: number;
+    duration?: number;
+}
+export interface MiniAppPerformanceEvent {
+    loadDuration?: number;
+    domReady?: number;
+    firstPaint?: number;
+    domExecutionDuration?: number;
+    resourceDuration?: number;
+    resourceCount?: number;
+    transferSize?: number;
+}
+export interface MiniAppCaptureEvent {
+    blob: Blob;
+}
+export interface MiniAppDestroyEvent {
+    reason?: string;
+}
+/** 页面路由变化（宿主 redirectTo / 头像点击 / 卡片点击 / sheet 开合 / 内存回收等统一触发） */
+export interface MiniAppRouterChangeEvent {
+    from: MiniAppSimulatorRoute;
+    to: MiniAppSimulatorRoute;
+}
+export interface MiniAppEventMap {
+    ready: MiniAppReadyEvent;
+    beforeLoad: MiniAppBeforeLoadEvent;
+    load: MiniAppLoadEvent;
+    renderDone: MiniAppRenderDoneEvent;
+    error: MiniAppErrorEvent;
+    navigation: MiniAppNavigationEvent;
+    console: MiniAppConsoleEvent;
+    guestError: MiniAppGuestErrorEvent;
+    network: MiniAppNetworkEvent;
+    performance: MiniAppPerformanceEvent;
+    capture: MiniAppCaptureEvent;
+    destroy: MiniAppDestroyEvent;
+    /** 页面切换（任意来源：宿主调用 / 模拟器内部交互） */
+    routerChange: MiniAppRouterChangeEvent;
+    /** 截图结果（auto 自动截图 + manual 主动截图均触发） */
+    screenShot: MiniAppScreenShotResult;
+    /** 选取模式下指针悬停到某元素（移出小应用区域时为 null） */
+    elementHovered: ElementSelection | null;
+    /** 选取模式下点击选中某元素 */
+    elementSelected: ElementSelection;
+    /** 单选 / 多选集合发生变化 */
+    elementSelectionChange: MiniAppElementSelectionChangeEvent;
+    /** DOM 与 Scene 统一悬停事件。 */
+    visualHovered: VisualSelection | null;
+    /** DOM 与 Scene 统一点击 / 反向选中事件。 */
+    visualSelected: VisualSelection;
+    /** DOM 与 Scene 混合选择集合变化事件。 */
+    visualSelectionChange: MiniAppVisualSelectionChangeEvent;
+    /** 选取模式开 / 关状态变化 */
+    inspectorChange: MiniAppInspectorChangeEvent;
+}
+export type MiniAppEventHandler<E extends MiniAppEventName> = (event: MiniAppEventMap[E]) => void;
+export type MiniAppErrorCode = "INVALID_URL" | "URL_BLOCKED" | "INVALID_ROUTE" | "LOAD_TIMEOUT" | "LOAD_FAILED" | "RENDERER_ERROR" | "UNSUPPORTED_RENDERER" | "LOADER_UNSUPPORTED" | "CAPTURE_UNSUPPORTED" | "ZIP_LOAD_FAILED" | "ZIP_NO_ENTRY" | "FILES_NO_ENTRY" | "PACKAGE_LIMIT_EXCEEDED" | "RESOURCE_LIMIT_EXCEEDED" | "DESTROYED";

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

@@ -0,0 +1,11 @@
+/**
+ * 公共类型 barrel —— 按领域拆分为 options / events / renderer 三个文件，
+ * 此处统一转出，保持 `from "../types"` 的导入路径不变。
+ */
+export type { MiniAppMountTarget } from "../host/shadow-host";
+export type { MiniAppPermissionKind, MiniAppPermissionSheetResult } from "../native-ui/permission-sheet/types";
+export * from "./options";
+export * from "./events";
+export * from "./renderer";
+export * from "./inspector";
+export * from "./jsapi";

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

@@ -0,0 +1,172 @@
+/**
+ * 可视化元素选取（Visual Inspector）公开类型。
+ *
+ * 能力定位：在预览态的小应用里「悬停高亮 + 点击选中」DOM 元素，把被选元素的
+ * 结构化描述（selector / 文本 / outerHTML 片段 / 包围盒）抛给宿主，供宿主拼进
+ * AI 编辑指令的上下文（Lovable / v0 式「@选区」体验）。
+ *
+ * 该能力完全独立于手势模拟（touchEmulation）：开启时在 iframe 之上盖一层独立
+ * overlay 接管指针，关闭时 overlay 不存在，**对现有渲染 / 手势 / jsapi 链路零影响**。
+ * 仅 iframe 渲染器 + 同源可访问（allowSameOrigin，默认随 touchEmulation 开启）时生效；
+ * webview / 跨源场景为 no-op。
+ */
+/** 被选中 / 悬停元素的结构化描述（坐标取 iframe 内容 CSS 像素空间） */
+export interface ElementSelection {
+    /** 统一 Visual Inspector 判别字段；旧消费方可忽略。 */
+    kind?: "dom";
+    /** 统一选区引用；DOM 默认由 selector 派生。 */
+    ref?: string;
+    /** 面向用户 / 输入胶囊的短标签，例如 `button.primary · 提交` */
+    label: string;
+    /** 从文档根到该元素的稳定 CSS selector（优先 #id 锚点，回退 :nth-of-type 路径） */
+    selector: string;
+    /** 从近端稳定锚点到元素的结构化 DOM 路径，供源码检索时逐级匹配 */
+    domPath: ElementPathSegment[];
+    /** 标签名（小写） */
+    tagName: string;
+    /** element id，无则 null */
+    id: string | null;
+    /** class 列表 */
+    classList: string[];
+    /** 归一化后的 textContent（折叠空白并截断），供 AI 识别"改哪段文案" */
+    text: string;
+    /** outerHTML 预览（截断），供 AI 理解元素结构 */
+    outerHTMLPreview: string;
+    /** 元素属性表（name → value） */
+    attributes: Record<string, string>;
+    /** iframe 内容坐标系下的包围盒（CSS px，未经设备缩放） */
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * 宿主视口（屏幕）坐标系下的包围盒（CSS px，已含设备缩放）。
+     * 即元素在整个页面里的真实屏幕位置，宿主可据此把浮动工具条 / chip 锚到选中元素旁。
+     */
+    viewportRect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/** 场景节点源码定位提示；definitionKey 跨 reload 稳定，instanceKey 只描述当前实例。 */
+export interface MiniAppSceneSourceHint {
+    file?: string;
+    symbol?: string;
+    definitionKey?: string;
+    instanceKey?: string;
+}
+/** 从场景根到当前节点的稳定语义路径。 */
+export interface MiniAppScenePathSegment {
+    ref: string;
+    label: string;
+    nodeType: string;
+}
+/** PixiJS / Three.js / 自定义 Canvas Provider 返回的结构化场景选区。 */
+export interface SceneSelection {
+    kind: "scene";
+    /** 单次预览会话内稳定、跨 Provider 唯一的节点引用。 */
+    ref: string;
+    providerId: string;
+    engine: string;
+    label: string;
+    nodeType: string;
+    nodePath: MiniAppScenePathSegment[];
+    /** 只读、可序列化的 Inspector 属性白名单。 */
+    properties: Record<string, unknown>;
+    source?: MiniAppSceneSourceHint;
+    /** iframe 内容坐标系下的包围盒。 */
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** 宿主视口坐标系下的包围盒，由 Host Inspector 补齐。 */
+    viewportRect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/** DOM 与场景对象在宿主侧汇聚后的统一选区。 */
+export type VisualSelection = ElementSelection | SceneSelection;
+/** Hierarchy / Outliner 使用的裁剪场景节点。 */
+export interface MiniAppSceneNode {
+    ref: string;
+    label: string;
+    nodeType: string;
+    visible: boolean;
+    selectable: boolean;
+    source?: MiniAppSceneSourceHint;
+    children: MiniAppSceneNode[];
+}
+/** 单个已注册 Provider 的场景树。 */
+export interface MiniAppSceneProviderTree {
+    providerId: string;
+    engine: string;
+    label: string;
+    roots: MiniAppSceneNode[];
+}
+/** `getSceneTree()` 的版本化只读快照。 */
+export interface MiniAppSceneTreeSnapshot {
+    version: 1;
+    providers: MiniAppSceneProviderTree[];
+}
+/** selector 的结构化路径段；比仅传字符串更便于 Agent 关联 Vue/React 模板源码 */
+export interface ElementPathSegment {
+    tagName: string;
+    id: string | null;
+    classList: string[];
+    /** 同标签兄弟中的 1-based 序号；唯一兄弟时为 1 */
+    nthOfType: number;
+}
+/** `inspectorChange` 事件载荷 */
+export interface MiniAppInspectorChangeEvent {
+    /** 选取模式是否开启 */
+    enabled: boolean;
+}
+export type MiniAppInspectorSelectionMode = "single" | "multiple";
+/** 多选集合变化事件；`elementSelected` 仍为单次新增事件以保持向后兼容 */
+export interface MiniAppElementSelectionChangeEvent {
+    selections: ElementSelection[];
+    changed: ElementSelection | null;
+    action: "add" | "clear";
+}
+/** DOM 与 Scene 混合选择集合变化事件。 */
+export interface MiniAppVisualSelectionChangeEvent {
+    selections: VisualSelection[];
+    changed: VisualSelection | null;
+    action: "add" | "clear" | "remove";
+}
+/**
+ * 运行时可视化选取控制器，挂在 `simulator.inspector` 上。
+ *
+ * 与 `gesture` / `hostApi` 等控制器同级，提供实例方法控制选取模式开关；
+ * 选中 / 悬停结果通过 `simulator.on('elementSelected' | 'elementHovered', ...)` 订阅。
+ * 仅 iframe 渲染器 + 同源可访问时生效，其余场景所有方法为 no-op。
+ */
+export interface MiniAppInspectorController {
+    /** 进入选取模式：冻结应用帧时钟并在小应用之上盖一层 overlay 接管悬停 / 点击 */
+    enable(): void;
+    /** 退出选取模式：恢复应用时钟，移除 overlay，恢复正常预览 / 手势交互 */
+    disable(): void;
+    /** 切换选取模式 */
+    toggle(): void;
+    /** 当前是否处于选取模式 */
+    isEnabled(): boolean;
+    /** 清除当前选中高亮（保持选取模式开启） */
+    clear(): void;
+    /** 单选 / 多选模式；默认 single。切换模式时会清空已有高亮。 */
+    setSelectionMode(mode: MiniAppInspectorSelectionMode): void;
+    /** 当前选取模式 */
+    getSelectionMode(): MiniAppInspectorSelectionMode;
+    /** 获取所有已注册 Scene Provider 的只读层级树；不支持时返回空快照。 */
+    getSceneTree(): Promise<MiniAppSceneTreeSnapshot>;
+    /** 从 Hierarchy / Outliner 反向选中场景节点，并同步 Viewport 高亮。 */
+    selectByRef(ref: string): Promise<VisualSelection | null>;
+}

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

@@ -0,0 +1,18 @@
+export declare enum MiniAppJsApiErrorCode {
+    INVALID_PARAM = 10001,
+    API_UNAVAILABLE = 10002,
+    URL_SCHEME_NOT_ALLOWED = 10003,
+    REQUEST_TIMEOUT = 10101,
+    REQUEST_ABORTED = 10102,
+    REQUEST_FAILED = 15201,
+    STORAGE_IO_ERROR = 50101,
+    STORAGE_QUOTA_EXCEEDED = 50201,
+    FILE_NOT_FOUND = 50202,
+    PATH_INVALID = 50203,
+    FILE_ALREADY_EXISTS = 50204,
+    NOT_A_FILE = 50205,
+    NOT_A_DIRECTORY = 50206
+}
+export declare function createMiniAppJsApiError(code: MiniAppJsApiErrorCode, message: string): Error & {
+    code: MiniAppJsApiErrorCode;
+};