ice-entity-designer 0.0.19 → 0.0.21

package/dist/types/designer/EntityDesigner.d.mts

@@ -66,7 +66,7 @@ export default class EntityDesigner {
      * @returns 载入报告（创建数量、被跳过的未知类型）
      */
     loadProject(json: string): ProjectLoadReport;
-    private __componentBaseSnapshot;
+    /** 节点快照由共享 codec 的字段定义驱动（写与校验同一份定义，见 utils/project_codec.ts） */
     private __entitySnapshot;
     private __slotPoint;
     private __relationSnapshot;

package/dist/types/designer/EntityDesigner.d.ts

@@ -66,7 +66,7 @@ export default class EntityDesigner {
      * @returns 载入报告（创建数量、被跳过的未知类型）
      */
     loadProject(json: string): ProjectLoadReport;
-    private __componentBaseSnapshot;
+    /** 节点快照由共享 codec 的字段定义驱动（写与校验同一份定义，见 utils/project_codec.ts） */
     private __entitySnapshot;
     private __slotPoint;
     private __relationSnapshot;

package/dist/types/er-component/Entity.d.mts

@@ -37,6 +37,11 @@ export default class Entity extends ICEGroup {
      * 属性名默认不会被压缩，子类也会继承这个值。
      */
     static readonly typeId = "Entity";
+    /**
+     * 表头背景 / 标题 / 分隔线 / 字段文本都是由 entityName、fields、各 style 派生的内部子组件，
+     * 构造函数会按 state 重建 → 不参与引擎序列化（避免往返重复挂载）。
+     */
+    hasDerivedChildren(): boolean;
     protected entityNameComponent: ICEText;
     protected headerBackgroundComponent: ICERect;
     protected deviderLine: ICEPolyLine;

package/dist/types/er-component/Entity.d.ts

@@ -37,6 +37,11 @@ export default class Entity extends ICEGroup {
      * 属性名默认不会被压缩，子类也会继承这个值。
      */
     static readonly typeId = "Entity";
+    /**
+     * 表头背景 / 标题 / 分隔线 / 字段文本都是由 entityName、fields、各 style 派生的内部子组件，
+     * 构造函数会按 state 重建 → 不参与引擎序列化（避免往返重复挂载）。
+     */
+    hasDerivedChildren(): boolean;
     protected entityNameComponent: ICEText;
     protected headerBackgroundComponent: ICERect;
     protected deviderLine: ICEPolyLine;

package/dist/types/er-component/Relation.d.mts

@@ -21,6 +21,8 @@ export default class Relation extends ICEVisioLink {
      * 下游打包会 mangle 类名（实测 webpack 生产构建下 Relation → `Br`），基于类名的判断会静默失效。
      */
     static readonly typeId = "Relation";
+    /** 连线没有子组件；声明派生以保证引擎序列化只持久化自身 state */
+    hasDerivedChildren(): boolean;
     constructor(props?: any);
     /**
      * 根据关系类型推断箭头方向，默认指向 FK 所在的一端。

package/dist/types/er-component/Relation.d.ts

@@ -21,6 +21,8 @@ export default class Relation extends ICEVisioLink {
      * 下游打包会 mangle 类名（实测 webpack 生产构建下 Relation → `Br`），基于类名的判断会静默失效。
      */
     static readonly typeId = "Relation";
+    /** 连线没有子组件；声明派生以保证引擎序列化只持久化自身 state */
+    hasDerivedChildren(): boolean;
     constructor(props?: any);
     /**
      * 根据关系类型推断箭头方向，默认指向 FK 所在的一端。

package/dist/types/flow/FlowDesigner.d.mts

@@ -1,20 +1,21 @@
+import type { ICE } from '../ice-render/index.mjs';
+import type { FlowNodeKind } from './FlowNode.mjs';
 /**
- * Copyright (c) 2022 大漠穷秋.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
+ * 流程图文档。
  *
+ * **直接复用引擎的序列化机制**：`scene` 是引擎 `Serializer` 的原生产物
+ * （`{ version, childNodes }`，只去掉 createTime/lastModifyTime 这类每次都会变的时间戳）。
+ * 于是「组件 state 上的一切」（含应用层自定义 `data`）自动往返，新字段不需要在任何清单里登记，
+ * 容错（未注册类型跳过 + unknownTypes）、版本迁移也全部沿用引擎那一套。
  */
-import type { ICE } from '../ice-render/index.mjs';
-import type { FlowNodeKind } from './FlowNode.mjs';
-import type { FlowEdgeSnapshot } from './FlowEdge.mjs';
-import type { FlowNodeSnapshot } from './FlowNode.mjs';
-/** 流程图快照：只含流程图自身的语义数据，跨版本可读 */
 export declare type FlowSnapshot = {
-    version: number;
+    version: 2;
     kind: 'flowchart';
-    nodes: FlowNodeSnapshot[];
-    edges: FlowEdgeSnapshot[];
+    scene: {
+        /** 引擎的序列化格式版本（SERIALIZATION_VERSION） */
+        version: number;
+        childNodes: any[];
+    };
 };
 /** load() 的载入报告 */
 export declare type FlowLoadReport = {
@@ -51,6 +52,19 @@ export default class FlowDesigner {
     private __maxHistory;
     private __listeners;
     private __mousedownHandler;
+    /** 画布拖拽节点时会话：BEFORE_MOVE 记一次历史，mouseup 结束会话 */
+    private __moveSession;
+    private __moveEmitQueued;
+    /**
+     * 节点在画布上被拖动（引擎 `setPosition()` → BEFORE_MOVE/AFTER_MOVE）。
+     *
+     * 这两个事件是**每一步移动都触发**的，所以：BEFORE_MOVE 只在会话内第一次记历史
+     * （此时 `setState` 还没执行，记下的是拖拽前的位置），AFTER_MOVE 按帧合并后广播，
+     * 避免拖动过程中每帧都序列化整个流程。
+     */
+    private __beforeMoveHandler;
+    private __afterMoveHandler;
+    private __mouseupHandler;
     constructor(ice: ICE);
     get nodes(): any[];
     get edges(): any[];
@@ -61,6 +75,12 @@ export default class FlowDesigner {
      */
     subscribe(listener: (snapshot: string, designer: FlowDesigner) => void): () => void;
     private __emitChange;
+    /** 订阅节点的拖拽事件：拖动是画布侧的行为，designer 需要感知才能广播与记历史 */
+    private __attachNodeListeners;
+    private __detachNodeListeners;
+    private __onBeforeMove;
+    private __onAfterMove;
+    private __endMoveSession;
     select(id: string | null): this;
     /** 没有给坐标时，按已有节点包围盒的下方网格错开摆放，避免新建节点互相压住 */
     private __defaultPlacement;
@@ -75,13 +95,23 @@ export default class FlowDesigner {
     clear(): void;
     serialize(): string;
     toSnapshot(): FlowSnapshot;
+    /** 引擎 Serializer / Deserializer：ice 未 init 时 ice.serializer 不存在，这里按需构造（两者无状态） */
+    private __serializer;
+    private __deserializer;
     /**
-     * 载入流程图快照（整体替换当前流程）。
+     * 载入流程图文档（整体替换当前流程）。
+     *
+     * 支持两种格式：
+     * - **v2（当前）**：`scene` 为引擎序列化产物 → 直接交给引擎 `Deserializer` 重建，
+     *   未注册类型会被跳过并记入报告的 `skipped`（沿用引擎的容错语义）；
+     * - **v1（历史）**：`nodes` / `edges` 数组 → 走兼容读取路径（迁移，不再作为写出格式）。
      *
      * @throws 结构非法时抛错；此时当前流程与历史栈都不会被改动。
      */
     load(json: string): FlowLoadReport;
-    /** 用快照数据重建整张流程图（不发变更广播，由调用方决定广播时机） */
+    /** v2：把引擎序列化产物交给引擎 Deserializer 重建（容错、类型分派全部复用引擎实现） */
+    private __applyEngineScene;
+    /** v1（历史格式）兼容读取：由 nodes / edges 数组重建（迁移路径，不参与写出） */
     private __clearAndBuild;
     /** 把整个流程缩放到画布可视区内 */
     fitViewport(padding?: number): void;

package/dist/types/flow/FlowDesigner.d.ts

@@ -1,20 +1,21 @@
+import type { ICE } from '../ice-render/index';
+import type { FlowNodeKind } from './FlowNode';
 /**
- * Copyright (c) 2022 大漠穷秋.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
+ * 流程图文档。
  *
+ * **直接复用引擎的序列化机制**：`scene` 是引擎 `Serializer` 的原生产物
+ * （`{ version, childNodes }`，只去掉 createTime/lastModifyTime 这类每次都会变的时间戳）。
+ * 于是「组件 state 上的一切」（含应用层自定义 `data`）自动往返，新字段不需要在任何清单里登记，
+ * 容错（未注册类型跳过 + unknownTypes）、版本迁移也全部沿用引擎那一套。
  */
-import type { ICE } from '../ice-render/index';
-import type { FlowNodeKind } from './FlowNode';
-import type { FlowEdgeSnapshot } from './FlowEdge';
-import type { FlowNodeSnapshot } from './FlowNode';
-/** 流程图快照：只含流程图自身的语义数据，跨版本可读 */
 export declare type FlowSnapshot = {
-    version: number;
+    version: 2;
     kind: 'flowchart';
-    nodes: FlowNodeSnapshot[];
-    edges: FlowEdgeSnapshot[];
+    scene: {
+        /** 引擎的序列化格式版本（SERIALIZATION_VERSION） */
+        version: number;
+        childNodes: any[];
+    };
 };
 /** load() 的载入报告 */
 export declare type FlowLoadReport = {
@@ -51,6 +52,19 @@ export default class FlowDesigner {
     private __maxHistory;
     private __listeners;
     private __mousedownHandler;
+    /** 画布拖拽节点时会话：BEFORE_MOVE 记一次历史，mouseup 结束会话 */
+    private __moveSession;
+    private __moveEmitQueued;
+    /**
+     * 节点在画布上被拖动（引擎 `setPosition()` → BEFORE_MOVE/AFTER_MOVE）。
+     *
+     * 这两个事件是**每一步移动都触发**的，所以：BEFORE_MOVE 只在会话内第一次记历史
+     * （此时 `setState` 还没执行，记下的是拖拽前的位置），AFTER_MOVE 按帧合并后广播，
+     * 避免拖动过程中每帧都序列化整个流程。
+     */
+    private __beforeMoveHandler;
+    private __afterMoveHandler;
+    private __mouseupHandler;
     constructor(ice: ICE);
     get nodes(): any[];
     get edges(): any[];
@@ -61,6 +75,12 @@ export default class FlowDesigner {
      */
     subscribe(listener: (snapshot: string, designer: FlowDesigner) => void): () => void;
     private __emitChange;
+    /** 订阅节点的拖拽事件：拖动是画布侧的行为，designer 需要感知才能广播与记历史 */
+    private __attachNodeListeners;
+    private __detachNodeListeners;
+    private __onBeforeMove;
+    private __onAfterMove;
+    private __endMoveSession;
     select(id: string | null): this;
     /** 没有给坐标时，按已有节点包围盒的下方网格错开摆放，避免新建节点互相压住 */
     private __defaultPlacement;
@@ -75,13 +95,23 @@ export default class FlowDesigner {
     clear(): void;
     serialize(): string;
     toSnapshot(): FlowSnapshot;
+    /** 引擎 Serializer / Deserializer：ice 未 init 时 ice.serializer 不存在，这里按需构造（两者无状态） */
+    private __serializer;
+    private __deserializer;
     /**
-     * 载入流程图快照（整体替换当前流程）。
+     * 载入流程图文档（整体替换当前流程）。
+     *
+     * 支持两种格式：
+     * - **v2（当前）**：`scene` 为引擎序列化产物 → 直接交给引擎 `Deserializer` 重建，
+     *   未注册类型会被跳过并记入报告的 `skipped`（沿用引擎的容错语义）；
+     * - **v1（历史）**：`nodes` / `edges` 数组 → 走兼容读取路径（迁移，不再作为写出格式）。
      *
      * @throws 结构非法时抛错；此时当前流程与历史栈都不会被改动。
      */
     load(json: string): FlowLoadReport;
-    /** 用快照数据重建整张流程图（不发变更广播，由调用方决定广播时机） */
+    /** v2：把引擎序列化产物交给引擎 Deserializer 重建（容错、类型分派全部复用引擎实现） */
+    private __applyEngineScene;
+    /** v1（历史格式）兼容读取：由 nodes / edges 数组重建（迁移路径，不参与写出） */
     private __clearAndBuild;
     /** 把整个流程缩放到画布可视区内 */
     fitViewport(padding?: number): void;

package/dist/types/flow/FlowEdge.d.mts

@@ -8,19 +8,6 @@
 import { ICEVisioLink } from '../ice-render/index.mjs';
 /** 连线端点所在的插槽位置（上 / 右 / 下 / 左 / 中心） */
 export declare type FlowPort = 'T' | 'R' | 'B' | 'L' | 'C';
-/** 连线在快照里的纯数据 */
-export declare type FlowEdgeSnapshot = {
-    id: string;
-    typeId: string;
-    sourceId: string | null;
-    targetId: string | null;
-    sourcePort: FlowPort | null;
-    targetPort: FlowPort | null;
-    label: string;
-    linkShape: string;
-    startPoint: number[];
-    endPoint: number[];
-};
 /**
  * @class FlowEdge 流程图连线
  *
@@ -29,7 +16,7 @@ export declare type FlowEdgeSnapshot = {
  */
 export default class FlowEdge extends ICEVisioLink {
     static readonly typeId = "FlowEdge";
+    /** 连线没有子组件；声明派生可保证将来即使加了内部装饰也不会被重复序列化 */
+    hasDerivedChildren(): boolean;
     constructor(props?: any);
-    /** 流程快照用的纯数据 */
-    toFlowObject(): FlowEdgeSnapshot;
 }

package/dist/types/flow/FlowEdge.d.ts

@@ -8,19 +8,6 @@
 import { ICEVisioLink } from '../ice-render/index';
 /** 连线端点所在的插槽位置（上 / 右 / 下 / 左 / 中心） */
 export declare type FlowPort = 'T' | 'R' | 'B' | 'L' | 'C';
-/** 连线在快照里的纯数据 */
-export declare type FlowEdgeSnapshot = {
-    id: string;
-    typeId: string;
-    sourceId: string | null;
-    targetId: string | null;
-    sourcePort: FlowPort | null;
-    targetPort: FlowPort | null;
-    label: string;
-    linkShape: string;
-    startPoint: number[];
-    endPoint: number[];
-};
 /**
  * @class FlowEdge 流程图连线
  *
@@ -29,7 +16,7 @@ export declare type FlowEdgeSnapshot = {
  */
 export default class FlowEdge extends ICEVisioLink {
     static readonly typeId = "FlowEdge";
+    /** 连线没有子组件；声明派生可保证将来即使加了内部装饰也不会被重复序列化 */
+    hasDerivedChildren(): boolean;
     constructor(props?: any);
-    /** 流程快照用的纯数据 */
-    toFlowObject(): FlowEdgeSnapshot;
 }

package/dist/types/flow/FlowNode.d.mts

@@ -19,19 +19,6 @@ export declare type FlowNodePreset = {
 };
 /** 各类型节点的默认尺寸与配色（同时作为属性面板的预设） */
 export declare const FLOW_NODE_KINDS: Record<FlowNodeKind, FlowNodePreset>;
-/** 流程图节点在快照里的纯数据（不含引擎内部状态） */
-export declare type FlowNodeSnapshot = {
-    id: string;
-    typeId: string;
-    kind: FlowNodeKind;
-    title: string;
-    left: number;
-    top: number;
-    width: number;
-    height: number;
-    fillColor: string;
-    strokeColor: string;
-};
 /**
  * @class FlowNode 流程图节点
  *
@@ -44,11 +31,14 @@ export default class FlowNode extends ICEGroup {
     static readonly typeId = "FlowNode";
     protected shapeComponent: any;
     protected labelComponent: any;
+    /**
+     * 内部子组件（形状 + 标题）由 kind/尺寸/配色派生，构造函数会重建 →
+     * 不参与引擎序列化（否则往返会重复挂载，且子组件 zIndex 抖动，见 ICEComponent.hasDerivedChildren）。
+     */
+    hasDerivedChildren(): boolean;
     constructor(props?: any);
     /** 按当前 kind / 尺寸 / 配色重建形状与标题（切换类型或改样式时调用） */
     private __buildShape;
     /** 改节点属性（标题 / 类型 / 配色 / 尺寸），必要时重建形状 */
     applyPatch(patch?: Record<string, any>): this;
-    /** 流程快照用的纯数据 */
-    toFlowObject(): FlowNodeSnapshot;
 }

package/dist/types/flow/FlowNode.d.ts

@@ -19,19 +19,6 @@ export declare type FlowNodePreset = {
 };
 /** 各类型节点的默认尺寸与配色（同时作为属性面板的预设） */
 export declare const FLOW_NODE_KINDS: Record<FlowNodeKind, FlowNodePreset>;
-/** 流程图节点在快照里的纯数据（不含引擎内部状态） */
-export declare type FlowNodeSnapshot = {
-    id: string;
-    typeId: string;
-    kind: FlowNodeKind;
-    title: string;
-    left: number;
-    top: number;
-    width: number;
-    height: number;
-    fillColor: string;
-    strokeColor: string;
-};
 /**
  * @class FlowNode 流程图节点
  *
@@ -44,11 +31,14 @@ export default class FlowNode extends ICEGroup {
     static readonly typeId = "FlowNode";
     protected shapeComponent: any;
     protected labelComponent: any;
+    /**
+     * 内部子组件（形状 + 标题）由 kind/尺寸/配色派生，构造函数会重建 →
+     * 不参与引擎序列化（否则往返会重复挂载，且子组件 zIndex 抖动，见 ICEComponent.hasDerivedChildren）。
+     */
+    hasDerivedChildren(): boolean;
     constructor(props?: any);
     /** 按当前 kind / 尺寸 / 配色重建形状与标题（切换类型或改样式时调用） */
     private __buildShape;
     /** 改节点属性（标题 / 类型 / 配色 / 尺寸），必要时重建形状 */
     applyPatch(patch?: Record<string, any>): this;
-    /** 流程快照用的纯数据 */
-    toFlowObject(): FlowNodeSnapshot;
 }

package/dist/types/ice-render/graphic/ICEComponent.d.mts

@@ -337,6 +337,18 @@ declare abstract class ICEComponent extends ICEEventTarget {
     protected doRender(): void;
     /** 判断两个边界盒是否在视觉上重合（用于避免重复绘制几乎相同的 min/max 框）。 */
     private __areBoundingBoxesNearlyEqual;
+    /**
+     * 内部子组件是否为「由自身 state 派生」的。
+     *
+     * 复合组件（构造时按 state 建立内部子组件的组件，如「卡片 = 底框 + 标题」）应当返回 true：
+     * 这些子组件在反序列化时会被构造函数重建，序列化它们只会造成**重复挂载**
+     * （先由构造函数建一份、再由 Deserializer 挂一份）、并且子组件的自动 zIndex 每次都会变，
+     * 让同一份数据的两次序列化结果不稳定。返回 true 后，Serializer / Deserializer 都会跳过
+     * 该组件的 childNodes —— 只持久化它自己的 state（真相源），子组件视为派生结果。
+     *
+     * 默认为 false（普通容器/叶子组件的子节点是「真数据」，必须序列化）。
+     */
+    hasDerivedChildren(): boolean;
     /**
      * 获取组件的最小包围盒，此盒子的变换矩阵与组件自身完全相同。
      * 此方法需要在 render() 之后调用，组件没有渲染时无法计算最小包围盒。

package/dist/types/ice-render/graphic/ICEComponent.d.ts

@@ -337,6 +337,18 @@ declare abstract class ICEComponent extends ICEEventTarget {
     protected doRender(): void;
     /** 判断两个边界盒是否在视觉上重合（用于避免重复绘制几乎相同的 min/max 框）。 */
     private __areBoundingBoxesNearlyEqual;
+    /**
+     * 内部子组件是否为「由自身 state 派生」的。
+     *
+     * 复合组件（构造时按 state 建立内部子组件的组件，如「卡片 = 底框 + 标题」）应当返回 true：
+     * 这些子组件在反序列化时会被构造函数重建，序列化它们只会造成**重复挂载**
+     * （先由构造函数建一份、再由 Deserializer 挂一份）、并且子组件的自动 zIndex 每次都会变，
+     * 让同一份数据的两次序列化结果不稳定。返回 true 后，Serializer / Deserializer 都会跳过
+     * 该组件的 childNodes —— 只持久化它自己的 state（真相源），子组件视为派生结果。
+     *
+     * 默认为 false（普通容器/叶子组件的子节点是「真数据」，必须序列化）。
+     */
+    hasDerivedChildren(): boolean;
     /**
      * 获取组件的最小包围盒，此盒子的变换矩阵与组件自身完全相同。
      * 此方法需要在 render() 之后调用，组件没有渲染时无法计算最小包围盒。

package/dist/types/ice-render/index.d.mts

@@ -51,5 +51,7 @@ export { default as ICE } from './ICE.mjs';
 export { default as CanvasRenderer } from './renderer/CanvasRenderer.mjs';
 export { default as PluginHost } from './plugin/PluginHost.mjs';
 export type { ICEPlugin, ICEPluginTool, ICERenderHook, ICERenderFrame } from './plugin/PluginHost.mjs';
+export { default as Serializer, SERIALIZATION_VERSION } from './persistence/Serializer.mjs';
+export { default as Deserializer, SERIALIZATION_MIGRATIONS } from './persistence/Deserializer.mjs';
 export { buildAccessibilityTree } from './a11y/accessibility.mjs';
 export type { ICEAccessibleNode, ICEAccessibleRole, ICEAccessibilityOptions } from './a11y/accessibility.mjs';

package/dist/types/ice-render/index.d.ts

@@ -51,5 +51,7 @@ export { default as ICE } from './ICE';
 export { default as CanvasRenderer } from './renderer/CanvasRenderer';
 export { default as PluginHost } from './plugin/PluginHost';
 export type { ICEPlugin, ICEPluginTool, ICERenderHook, ICERenderFrame } from './plugin/PluginHost';
+export { default as Serializer, SERIALIZATION_VERSION } from './persistence/Serializer';
+export { default as Deserializer, SERIALIZATION_MIGRATIONS } from './persistence/Deserializer';
 export { buildAccessibilityTree } from './a11y/accessibility';
 export type { ICEAccessibleNode, ICEAccessibleRole, ICEAccessibilityOptions } from './a11y/accessibility';

package/dist/types/index.d.mts

@@ -14,9 +14,9 @@ export { toSchemaObject, toSchemaString } from './utils/serialization_util.mjs';
 export { validateSchema } from './utils/schema_validator.mjs';
 export { PROJECT_SCHEMA_VERSION, validateProjectSnapshot } from './utils/project_schema.mjs';
 export { default as FlowNode, FLOW_NODE_KINDS } from './flow/FlowNode.mjs';
-export type { FlowNodeKind, FlowNodePreset, FlowNodeSnapshot } from './flow/FlowNode.mjs';
+export type { FlowNodeKind, FlowNodePreset } from './flow/FlowNode.mjs';
 export { default as FlowEdge } from './flow/FlowEdge.mjs';
-export type { FlowPort, FlowEdgeSnapshot } from './flow/FlowEdge.mjs';
+export type { FlowPort } from './flow/FlowEdge.mjs';
 export { default as FlowDesigner, validateFlowSnapshot } from './flow/FlowDesigner.mjs';
 export type { FlowSnapshot, FlowLoadReport, FlowSnapshotValidationResult } from './flow/FlowDesigner.mjs';
 export { FlowDiamond, FlowParallelogram } from './flow/flow_shapes.mjs';

package/dist/types/index.d.ts

@@ -14,9 +14,9 @@ export { toSchemaObject, toSchemaString } from './utils/serialization_util';
 export { validateSchema } from './utils/schema_validator';
 export { PROJECT_SCHEMA_VERSION, validateProjectSnapshot } from './utils/project_schema';
 export { default as FlowNode, FLOW_NODE_KINDS } from './flow/FlowNode';
-export type { FlowNodeKind, FlowNodePreset, FlowNodeSnapshot } from './flow/FlowNode';
+export type { FlowNodeKind, FlowNodePreset } from './flow/FlowNode';
 export { default as FlowEdge } from './flow/FlowEdge';
-export type { FlowPort, FlowEdgeSnapshot } from './flow/FlowEdge';
+export type { FlowPort } from './flow/FlowEdge';
 export { default as FlowDesigner, validateFlowSnapshot } from './flow/FlowDesigner';
 export type { FlowSnapshot, FlowLoadReport, FlowSnapshotValidationResult } from './flow/FlowDesigner';
 export { FlowDiamond, FlowParallelogram } from './flow/flow_shapes';

package/dist/types/react/FlowDesignerCanvas.d.mts

@@ -0,0 +1,14 @@
+import type { FlowDesignerCanvasProps } from './types.mjs';
+/**
+ * <FlowDesignerCanvas> —— 在 React 中承载流程图编辑器的画布组件。
+ *
+ * 与 <EntityDesignerCanvas> 同构：挂载创建 ICE + FlowDesigner 会话、卸载销毁；
+ * 支持受控 value / 非受控 defaultValue、onChange（含画布拖拽节点）、onError 与命令式 ref。
+ *
+ * ```tsx
+ * const ref = useRef<FlowDesignerHandle>(null);
+ * <FlowDesignerCanvas ref={ref} defaultValue={flowJson} onChange={({ snapshot }) => save(snapshot)} />
+ * ```
+ */
+declare const FlowDesignerCanvas: import("react").ForwardRefExoticComponent<FlowDesignerCanvasProps & import("react").RefAttributes<any>>;
+export default FlowDesignerCanvas;

package/dist/types/react/FlowDesignerCanvas.d.ts

@@ -0,0 +1,14 @@
+import type { FlowDesignerCanvasProps } from './types';
+/**
+ * <FlowDesignerCanvas> —— 在 React 中承载流程图编辑器的画布组件。
+ *
+ * 与 <EntityDesignerCanvas> 同构：挂载创建 ICE + FlowDesigner 会话、卸载销毁；
+ * 支持受控 value / 非受控 defaultValue、onChange（含画布拖拽节点）、onError 与命令式 ref。
+ *
+ * ```tsx
+ * const ref = useRef<FlowDesignerHandle>(null);
+ * <FlowDesignerCanvas ref={ref} defaultValue={flowJson} onChange={({ snapshot }) => save(snapshot)} />
+ * ```
+ */
+declare const FlowDesignerCanvas: import("react").ForwardRefExoticComponent<FlowDesignerCanvasProps & import("react").RefAttributes<any>>;
+export default FlowDesignerCanvas;

package/dist/types/react/context.d.mts

@@ -1,4 +1,4 @@
-import type { EntityDesigner } from '../index.mjs';
+import type { EntityDesigner, FlowDesigner } from '../index.mjs';
 /**
  * React 绑定层上下文：承载当前画布对应的 EntityDesigner 实例。
  * 由 <EntityDesignerCanvas>（或 <EntityDesignerProvider>）提供，供子树内的 useEntityDesigner() 读取。
@@ -23,3 +23,20 @@ export declare function EntityDesignerProvider(props: EntityDesignerProviderProp
  * 只能在 <EntityDesignerCanvas> / <EntityDesignerProvider> 的子树中使用；未就绪或不在树中时返回 null。
  */
 export declare function useEntityDesigner(): EntityDesigner | null;
+/**
+ * 流程图上下文：承载当前画布对应的 FlowDesigner 实例。
+ * 由 <FlowDesignerCanvas>（或 <FlowDesignerProvider>）提供，供子树内的 useFlowDesigner() 读取。
+ */
+export declare const FlowDesignerContext: import("react").Context<FlowDesigner>;
+export declare type FlowDesignerProviderProps = {
+    /** 要共享的 FlowDesigner 实例（通常来自 createFlowSession） */
+    designer: FlowDesigner | null;
+    children?: any;
+};
+/** 手动提供流程图上下文。适用于「自己创建会话」的场景。 */
+export declare function FlowDesignerProvider(props: FlowDesignerProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<FlowDesigner>>;
+/**
+ * 读取当前画布的 FlowDesigner 实例。
+ * 只能在 <FlowDesignerCanvas> / <FlowDesignerProvider> 的子树中使用；未就绪或不在树中时返回 null。
+ */
+export declare function useFlowDesigner(): FlowDesigner | null;

package/dist/types/react/context.d.ts

@@ -1,4 +1,4 @@
-import type { EntityDesigner } from '../index';
+import type { EntityDesigner, FlowDesigner } from '../index';
 /**
  * React 绑定层上下文：承载当前画布对应的 EntityDesigner 实例。
  * 由 <EntityDesignerCanvas>（或 <EntityDesignerProvider>）提供，供子树内的 useEntityDesigner() 读取。
@@ -23,3 +23,20 @@ export declare function EntityDesignerProvider(props: EntityDesignerProviderProp
  * 只能在 <EntityDesignerCanvas> / <EntityDesignerProvider> 的子树中使用；未就绪或不在树中时返回 null。
  */
 export declare function useEntityDesigner(): EntityDesigner | null;
+/**
+ * 流程图上下文：承载当前画布对应的 FlowDesigner 实例。
+ * 由 <FlowDesignerCanvas>（或 <FlowDesignerProvider>）提供，供子树内的 useFlowDesigner() 读取。
+ */
+export declare const FlowDesignerContext: import("react").Context<FlowDesigner>;
+export declare type FlowDesignerProviderProps = {
+    /** 要共享的 FlowDesigner 实例（通常来自 createFlowSession） */
+    designer: FlowDesigner | null;
+    children?: any;
+};
+/** 手动提供流程图上下文。适用于「自己创建会话」的场景。 */
+export declare function FlowDesignerProvider(props: FlowDesignerProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<FlowDesigner>>;
+/**
+ * 读取当前画布的 FlowDesigner 实例。
+ * 只能在 <FlowDesignerCanvas> / <FlowDesignerProvider> 的子树中使用；未就绪或不在树中时返回 null。
+ */
+export declare function useFlowDesigner(): FlowDesigner | null;

package/dist/types/react/index.d.mts

@@ -14,4 +14,11 @@ export type { EntityDesignerProviderProps } from './context.mjs';
 export { createDesignerSession, shouldApplyControlledValue } from './session.mjs';
 export type { DesignerSession, DesignerSessionOptions } from './session.mjs';
 export type { EntityDesignerCanvasProps, EntityDesignerChangePayload, EntityDesignerHandle } from './types.mjs';
-export { Entity, Relation, toSchemaObject, toSchemaString, validateSchema } from '../index.mjs';
+export { default as FlowDesignerCanvas } from './FlowDesignerCanvas.mjs';
+export { FlowDesignerContext, FlowDesignerProvider, useFlowDesigner } from './context.mjs';
+export type { FlowDesignerProviderProps } from './context.mjs';
+export { createFlowSession } from './session.mjs';
+export type { FlowSession, FlowSessionOptions } from './session.mjs';
+export type { FlowDesignerCanvasProps, FlowDesignerChangePayload, FlowDesignerHandle } from './types.mjs';
+export { Entity, Relation, FlowNode, FlowEdge, FlowDesigner, FLOW_NODE_KINDS, toSchemaObject, toSchemaString, validateSchema, } from '../index.mjs';
+export type { FlowNodeKind, FlowNodePreset, FlowPort, FlowSnapshot, FlowLoadReport } from '../index.mjs';

package/dist/types/react/index.d.ts

@@ -14,4 +14,11 @@ export type { EntityDesignerProviderProps } from './context';
 export { createDesignerSession, shouldApplyControlledValue } from './session';
 export type { DesignerSession, DesignerSessionOptions } from './session';
 export type { EntityDesignerCanvasProps, EntityDesignerChangePayload, EntityDesignerHandle } from './types';
-export { Entity, Relation, toSchemaObject, toSchemaString, validateSchema } from '../index';
+export { default as FlowDesignerCanvas } from './FlowDesignerCanvas';
+export { FlowDesignerContext, FlowDesignerProvider, useFlowDesigner } from './context';
+export type { FlowDesignerProviderProps } from './context';
+export { createFlowSession } from './session';
+export type { FlowSession, FlowSessionOptions } from './session';
+export type { FlowDesignerCanvasProps, FlowDesignerChangePayload, FlowDesignerHandle } from './types';
+export { Entity, Relation, FlowNode, FlowEdge, FlowDesigner, FLOW_NODE_KINDS, toSchemaObject, toSchemaString, validateSchema, } from '../index';
+export type { FlowNodeKind, FlowNodePreset, FlowPort, FlowSnapshot, FlowLoadReport } from '../index';

package/dist/types/react/reportLoadError.d.mts

@@ -0,0 +1,8 @@
+import type { EntityDesignerErrorPayload } from './types.mjs';
+/**
+ * 载入快照失败时上报给 onError（默认 console.error）。
+ *
+ * React 绑定层的两处 loadProject / load 都走这里兜底：非法 / 版本不兼容的快照
+ * 只会被上报，不会把异常抛进 React 渲染树（挂载期抛错会直接崩掉整棵子树）。
+ */
+export declare function reportLoadError(handler: ((payload: EntityDesignerErrorPayload) => void) | undefined, phase: EntityDesignerErrorPayload['phase'], snapshot: string, error: unknown): void;

package/dist/types/react/reportLoadError.d.ts

@@ -0,0 +1,8 @@
+import type { EntityDesignerErrorPayload } from './types';
+/**
+ * 载入快照失败时上报给 onError（默认 console.error）。
+ *
+ * React 绑定层的两处 loadProject / load 都走这里兜底：非法 / 版本不兼容的快照
+ * 只会被上报，不会把异常抛进 React 渲染树（挂载期抛错会直接崩掉整棵子树）。
+ */
+export declare function reportLoadError(handler: ((payload: EntityDesignerErrorPayload) => void) | undefined, phase: EntityDesignerErrorPayload['phase'], snapshot: string, error: unknown): void;

package/dist/types/react/session.d.mts

@@ -1,4 +1,4 @@
-import { EntityDesigner } from '../index.mjs';
+import { EntityDesigner, FlowDesigner } from '../index.mjs';
 export declare type DesignerSessionOptions = {
     /** 渲染模式，默认 dirty-rect */
     renderMode?: 'dirty-rect' | 'full';
@@ -28,3 +28,24 @@ export declare function createDesignerSession(canvas: any, options?: DesignerSes
  * 此时 lastApplied 已经等于该值，因此这里返回 false，避免「onChange → setState → 再 loadProject」的回环。
  */
 export declare function shouldApplyControlledValue(value: string | undefined, lastApplied: string | null | undefined): boolean;
+export declare type FlowSessionOptions = {
+    /** 渲染模式，默认 dirty-rect */
+    renderMode?: 'dirty-rect' | 'full';
+    /** 初始流程图快照，等价于 load(initialFlow) */
+    initialFlow?: string;
+    /** 流程变更回调（含画布拖动节点） */
+    onChange?: (snapshot: string) => void;
+};
+export declare type FlowSession = {
+    ice: any;
+    designer: FlowDesigner;
+    /** 销毁会话：退订 + dispose designer + destroy ICE（可重复调用） */
+    destroy(): void;
+};
+/**
+ * 在给定的 canvas 元素上创建「ICE + FlowDesigner」会话。
+ *
+ * 与 createDesignerSession 同构：挂载即初始化、卸载即销毁；ICE.init() 幂等、
+ * ICE.destroy() 会解绑全局监听与事件总线，因此 StrictMode 双挂载不会累积监听。
+ */
+export declare function createFlowSession(canvas: any, options?: FlowSessionOptions): FlowSession;