@cfp-studio/iframe 18.0.1 → 18.2.0

package/README.md

@@ -0,0 +1,37 @@
+# @cfp-studio/iframe
+
+CFP Studio 预览 iframe 通信与渲染核心包，负责 iframe 与主应用/设计器的消息通信、状态同步、渲染控制、HMR 支持等。
+
+## 特性
+- 提供 iframe 与父窗口的高效通信协议
+- 支持渲染状态、事件、错误、刷新等多种消息类型
+- 支持 HMR（热模块替换）与自动刷新
+- 兼容多框架渲染器（通过 preview/renderer/）
+- 支持全局状态、事件上报、调试等
+
+## 架构与工作原理
+- 通过全局 `__PREVIEWJS_IFRAME__` 对象暴露渲染、刷新、事件上报等能力
+- 预览页面（preview/index.html）自动注入全局对象与通信桥
+- 支持与主应用/设计器的双向事件流与状态同步
+- 支持多渲染器、错误处理、调试工具等扩展
+
+## 主要 API/模块
+- `src/index.ts`：iframe 通信与状态主入口
+- `preview/index.html`：预览页面模板，注入全局对象
+- `preview/__previewjs_internal__/`：内部工具与渲染控制
+- `preview/renderer/`：多框架渲染器入口
+
+## 用法示例
+
+集成于 CFP Studio 设计器/主应用，无需单独调用。自定义渲染器可参考 preview/renderer/
+
+## 依赖
+- `assert-never`、`immer`、`typescript`、`vite`、`unbuild`
+
+## 构建
+```sh
+pnpm build
+```
+
+## 许可证
+MIT

package/dist/index.d.mts

@@ -1,126 +1,145 @@
-import { UpdatePayload } from 'vite/types/hmrPayload';
-
+//#region ../node_modules/.pnpm/vite@6.4.5_@types+node@24.19.2_jiti@2.6.1_less@4.2.2_lightningcss@1.30.2_sass@1.85.1_terser@5.40.0_tsx@4.19.3_yaml@2.7.0/node_modules/vite/types/hmrPayload.d.ts
+interface UpdatePayload {
+  type: 'update';
+  updates: Update[];
+}
+interface Update {
+  type: 'js-update' | 'css-update';
+  path: string;
+  acceptedPath: string;
+  timestamp: number;
+  /** @internal */
+  explicitImportRequired?: boolean;
+  /** @internal */
+  isWithinCircularImport?: boolean;
+  /** @internal */
+  firstInvalidatedBy?: string;
+  /** @internal */
+  invalidates?: string[];
+}
+//#endregion
+//#region src/index.d.ts
 /**
  * 扩展全局 Window 对象，定义在 iframe 和其父窗口中使用的特定属性
  */
 declare global {
-    interface Window {
-        /**
-         * iframe 中暴露的对象，用于管理渲染状态和报告事件
-         */
-        __PREVIEWJS_IFRAME__: {
-            /**
-             * 表示最后一次渲染是否失败
-             */
-            lastRenderFailed: boolean;
-            toggleInspect: boolean;
-            /**
-             * 处理 HMR 更新
-             * @param payload - HMR 更新的负载
-             */
-            /**
-             * 报告预览事件
-             * @param event - 预览事件对象
-             */
-            reportEvent(event: PreviewEvent): void;
-            /**
-             * 刷新预览，可选参数指定刷新选项
-             * @param options - 刷新选项
-             */
-            refresh(options?: RefreshOptions): void;
-            /**
-             * 渲染预览，可选异步函数，接收渲染选项
-             * @param options - 渲染选项
-             * @returns 渲染完成的 Promise
-             */
-            render?(options: RenderOptions): Promise<void>;
-        };
-        /**
-         * 通常在 iframe 的父窗口中暴露，用于跟踪 iframe 的状态
-         */
-        __PREVIEWJS_CONTROLLER__: {
-            /**
-             * 处理预览事件
-             * @param event - 预览事件对象
-             */
-            onPreviewEvent(event: PreviewEvent): void;
-        };
-    }
+  interface Window {
+    /**
+     * iframe 中暴露的对象，用于管理渲染状态和报告事件
+     */
+    __PREVIEWJS_IFRAME__: {
+      /**
+       * 表示最后一次渲染是否失败
+       */
+      lastRenderFailed: boolean;
+      toggleInspect: boolean;
+      /**
+       * 处理 HMR 更新
+       * @param payload - HMR 更新的负载
+       */
+      /**
+       * 报告预览事件
+       * @param event - 预览事件对象
+       */
+      reportEvent(event: PreviewEvent): void;
+      /**
+       * 刷新预览，可选参数指定刷新选项
+       * @param options - 刷新选项
+       */
+      refresh(options?: RefreshOptions): void;
+      /**
+       * 渲染预览，可选异步函数，接收渲染选项
+       * @param options - 渲染选项
+       * @returns 渲染完成的 Promise
+       */
+      render?(options: RenderOptions): Promise<void>;
+    };
+    /**
+     * 通常在 iframe 的父窗口中暴露，用于跟踪 iframe 的状态
+     */
+    __PREVIEWJS_CONTROLLER__: {
+      /**
+       * 处理预览事件
+       * @param event - 预览事件对象
+       */
+      onPreviewEvent(event: PreviewEvent): void;
+    };
+  }
 }
 /**
  * 刷新预览的选项
  */
 type RefreshOptions = {
-    /**
-     * 是否重新获取可预览模块
-     */
-    refetchPreviewableModule?: boolean;
-    /**
-     * 是否重新获取包装模块
-     * added by Anthony on 2025-04-08
-     */
-    refetchWrapperModule?: boolean;
-    /**
-     * 可预览模块
-     */
-    previewableModule?: any;
-    /**
-     * 包装模块
-     */
-    wrapperModule?: any;
+  /**
+   * 是否重新获取可预览模块
+   */
+  refetchPreviewableModule?: boolean;
+  /**
+   * 是否重新获取包装模块
+   * added by Anthony on 2025-04-08
+   */
+  refetchWrapperModule?: boolean;
+  /**
+   * 可预览模块
+   */
+  previewableModule?: any;
+  /**
+   * 包装模块
+   */
+  wrapperModule?: any;
 };
 /**
  * 预览 iframe 的状态
  */
 type PreviewIframeState = {
-    /**
-     * 表示是否正在加载
-     */
-    loading: boolean;
-    /**
-     * 表示是否已经渲染
-     */
-    rendered: boolean;
-    /**
-     * 预览错误列表
-     */
-    errors: PreviewError[];
-    /**
-     * 日志消息列表
-     */
-    logs: LogMessage[];
-    /**
-     * 操作列表
-     */
-    actions: Action[];
+  /**
+   * 表示是否正在加载
+   */
+  loading: boolean;
+  /**
+   * 表示是否已经渲染
+   */
+  rendered: boolean;
+  /**
+   * 预览错误列表
+   */
+  errors: PreviewError[];
+  /**
+   * 日志消息列表
+   */
+  logs: LogMessage[];
+  /**
+   * 操作列表
+   */
+  actions: Action[];
 };
 /**
  * 创建控制器的选项
  */
 type CreateControllerOptions = {
-    /**
-     * 获取 iframe 元素的函数
-     * @returns HTMLIFrameElement 或 null
-     */
-    getIframe: () => HTMLIFrameElement | null;
-    /**
-     * 状态更新时的回调函数
-     * @param state - 预览 iframe 的状态
-     */
-    onStateUpdate?: (state: PreviewIframeState) => void;
+  /**
+   * 获取 iframe 元素的函数
+   * @returns HTMLIFrameElement 或 null
+   */
+  getIframe: () => HTMLIFrameElement | null;
+  /**
+   * 状态更新时的回调函数
+   * @param state - 预览 iframe 的状态
+   */
+  onStateUpdate?: (state: PreviewIframeState) => void;
 };
 /**
  * 渲染选项
  */
 type RenderOptions = {
-    /**
-     * 自动生成的回调属性源代码
-     */
-    autogenCallbackPropsSource: string;
-    /**
-     * 属性赋值源代码
-     */
-    propsAssignmentSource: string;
+  /**
+   * 自动生成的回调属性源代码
+   */
+  autogenCallbackPropsSource: string;
+  /**
+   * 属性赋值源代码
+   */
+  propsAssignmentSource: string;
 };
 /**
  * 创建预览 iframe 控制器
@@ -132,108 +151,108 @@ declare function createController(options: CreateControllerOptions): PreviewIfra
  * 预览 iframe 控制器接口
  */
 type PreviewIframeController = {
-    /**
-     * 渲染预览
-     * @param previewableId - 可预览项的 ID
-     * @param options - 渲染选项
-     */
-    render(previewableId: string, options: RenderOptions): void;
+  /**
+   * 渲染预览
+   * @param previewableId - 可预览项的 ID
+   * @param options - 渲染选项
+   */
+  render(previewableId: string, options: RenderOptions): void;
 };
 /**
  * 预览事件类型
  */
 type PreviewEvent = Bootstrapping | Bootstrapped | ViteBeforeUpdate | ViteAfterUpdate | ViteInvalidate | ViteBeforeReload | BeforeRender | Rendered | Action | LogMessage | PreviewError | ToggleInspect;
 type ToggleInspect = {
-    kind: "toggle-inspect";
-    enabled: boolean;
+  kind: "toggle-inspect";
+  enabled: boolean;
 };
 /**
  * 正在初始化事件
  */
 type Bootstrapping = {
-    kind: "bootstrapping";
+  kind: "bootstrapping";
 };
 /**
  * 初始化完成事件
  */
 type Bootstrapped = {
-    kind: "bootstrapped";
+  kind: "bootstrapped";
 };
 /**
  * Vite 预更新事件
  */
 type ViteBeforeUpdate = {
-    kind: "vite-before-update";
-    payload: UpdatePayload;
+  kind: "vite-before-update";
+  payload: UpdatePayload;
 };
 /**
  * Vite 更新后事件
  */
 type ViteAfterUpdate = {
-    kind: "vite-after-update";
-    payload: UpdatePayload;
+  kind: "vite-after-update";
+  payload: UpdatePayload;
 };
 /**
  * Vite 失效事件
  */
 type ViteInvalidate = {
-    kind: "vite-invalidate";
+  kind: "vite-invalidate";
 };
 /**
  * Vite 预重载事件
  */
 type ViteBeforeReload = {
-    kind: "vite-before-reload";
+  kind: "vite-before-reload";
 };
 /**
  * 渲染前事件
  */
 type BeforeRender = {
-    kind: "before-render";
+  kind: "before-render";
 };
 /**
  * 渲染完成事件
  */
 type Rendered = {
-    kind: "rendered";
+  kind: "rendered";
 };
 /**
  * 操作事件
  */
 type Action = {
-    kind: "action";
-    type: "fn" | "url";
-    path: string;
+  kind: "action";
+  type: "fn" | "url";
+  path: string;
 };
 /**
  * 日志消息事件
  */
 type LogMessage = {
-    kind: "log-message";
-    level: LogLevel;
-    message: string;
-    timestamp: number;
+  kind: "log-message";
+  level: LogLevel;
+  message: string;
+  timestamp: number;
 };
 /**
  * 预览错误事件
  */
 type PreviewError = {
-    kind: "error";
-    source: "load";
-    message: string;
+  kind: "error";
+  source: "load";
+  message: string;
 } | {
-    kind: "error";
-    source: "hmr";
-    modulePath: string;
-    message: string;
+  kind: "error";
+  source: "hmr";
+  modulePath: string;
+  message: string;
 } | {
-    kind: "error";
-    source: "vite";
-    message: string;
+  kind: "error";
+  source: "vite";
+  message: string;
 } | {
-    kind: "error";
-    source: "renderer";
-    message: string;
+  kind: "error";
+  source: "renderer";
+  message: string;
 };
 /**
  * 日志级别
@@ -245,15 +264,15 @@ type LogLevel = "log" | "info" | "warn" | "error";
  * @returns 包含渲染函数和 JSX 工厂函数的对象
  */
 type RendererLoader = (options: {
-    wrapperModule: any;
-    wrapperName?: string;
-    previewableModule: any;
-    previewableName: string;
-    renderId: number;
-    shouldAbortRender: () => boolean;
+  wrapperModule: any;
+  wrapperName?: string;
+  previewableModule: any;
+  previewableName: string;
+  renderId: number;
+  shouldAbortRender: () => boolean;
 }) => Promise<{
-    render: (getProps: GetPropsFn) => Promise<void>;
-    jsxFactory: ((type: any, props: any, ...children: any[]) => any) | null;
+  render: (getProps: GetPropsFn) => Promise<void>;
+  jsxFactory: ((type: any, props: any, ...children: any[]) => any) | null;
 }>;
 /**
  * 获取属性函数
@@ -261,8 +280,8 @@ type RendererLoader = (options: {
  * @returns 属性对象
  */
 type GetPropsFn = (options: {
-    presetGlobalProps: any;
-    presetProps: any;
+  presetGlobalProps: any;
+  presetProps: any;
 }) => Record<string, any>;
-
-export { type Action, type BeforeRender, type Bootstrapped, type Bootstrapping, type CreateControllerOptions, type GetPropsFn, type LogLevel, type LogMessage, type PreviewError, type PreviewEvent, type PreviewIframeController, type PreviewIframeState, type RefreshOptions, type RenderOptions, type Rendered, type RendererLoader, type ToggleInspect, type ViteAfterUpdate, type ViteBeforeReload, type ViteBeforeUpdate, type ViteInvalidate, createController };
+//#endregion
+export { Action, BeforeRender, Bootstrapped, Bootstrapping, CreateControllerOptions, GetPropsFn, LogLevel, LogMessage, PreviewError, PreviewEvent, PreviewIframeController, PreviewIframeState, RefreshOptions, RenderOptions, Rendered, RendererLoader, ToggleInspect, ViteAfterUpdate, ViteBeforeReload, ViteBeforeUpdate, ViteInvalidate, createController };