ice-entity-designer 0.0.20 → 0.0.22

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

@@ -6,8 +6,18 @@
  *
  */
 import { ICEGroup } from '../ice-render/index.mjs';
-/** 流程图节点类型：起止 / 处理 / 判定 / 输入输出 */
-export declare type FlowNodeKind = 'terminator' | 'process' | 'decision' | 'io';
+/**
+ * 节点类型词汇表。
+ *
+ * - 流程图：`terminator` / `process` / `decision` / `io`
+ * - BPMN 2.0：`bpmnEvent` / `bpmnTask` / `bpmnGateway` / `bpmnSubprocess` /
+ *   `bpmnDataObject` / `bpmnAnnotation` / `bpmnPool` / `bpmnLane`
+ *
+ * BPMN 复用同一套节点/连线/历史/快照机制（都是 `FlowNode`），语义差异由 `kind`
+ * 与 BPMN 专属属性（eventKind / trigger / gatewayType / taskType / band）承载，
+ * 因此文档、React 绑定、DSL 都不需要第二套实现。
+ */
+export declare type FlowNodeKind = 'terminator' | 'process' | 'decision' | 'io' | 'bpmnEvent' | 'bpmnTask' | 'bpmnGateway' | 'bpmnSubprocess' | 'bpmnDataObject' | 'bpmnAnnotation' | 'bpmnPool' | 'bpmnLane';
 export declare type FlowNodePreset = {
     label: string;
     width: number;
@@ -15,23 +25,28 @@ export declare type FlowNodePreset = {
     fill: string;
     stroke: string;
     radius?: number;
-    shape: 'rect' | 'diamond' | 'parallelogram';
+    shape: 'rect' | 'diamond' | 'parallelogram' | 'event' | 'gateway' | 'dataObject' | 'annotation' | 'lane';
+    /** 外框线宽（BPMN 结束事件用粗圈） */
+    lineWidth?: number;
+    /** 虚线（注释框） */
+    lineDash?: number[];
+    /** 名称带：泳道在左、池在顶 */
+    band?: 'left' | 'top';
+    bandSize?: number;
+    /** 标题摆放：居中（图元）或左上（池/泳道/注释） */
+    labelPlacement?: 'center' | 'top-left';
+    /** 背景透明（泳道用：相邻泳道共享边界时，填充会盖住邻居的边框） */
+    transparent?: boolean;
+    /** 默认的任务类型角标（bpmnTask 用） */
+    taskType?: string;
+    /** 默认事件种类 / 触发（bpmnEvent 用） */
+    eventKind?: string;
+    trigger?: string;
+    /** 默认网关类型（bpmnGateway 用） */
+    gatewayType?: string;
 };
 /** 各类型节点的默认尺寸与配色（同时作为属性面板的预设） */
 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 +59,23 @@ export default class FlowNode extends ICEGroup {
     static readonly typeId = "FlowNode";
     protected shapeComponent: any;
     protected labelComponent: any;
+    /** BPMN 装饰件（任务角标 / 子流程标记），随形状一起重建 */
+    protected decorationComponents: any[];
+    /**
+     * 内部子组件（形状 + 标题）由 kind/尺寸/配色派生，构造函数会重建 →
+     * 不参与引擎序列化（否则往返会重复挂载，且子组件 zIndex 抖动，见 ICEComponent.hasDerivedChildren）。
+     */
+    hasDerivedChildren(): boolean;
     constructor(props?: any);
     /** 按当前 kind / 尺寸 / 配色重建形状与标题（切换类型或改样式时调用） */
     private __buildShape;
+    /**
+     * BPMN 装饰件（任务类型角标、子流程折叠标记）。
+     *
+     * 它们与形状/标题一样由节点 state 派生，因此不需要单独序列化
+     * （见 hasDerivedChildren：整个内部子树都是派生的）。
+     */
+    private __buildDecorations;
     /** 改节点属性（标题 / 类型 / 配色 / 尺寸），必要时重建形状 */
     applyPatch(patch?: Record<string, any>): this;
-    /** 流程快照用的纯数据 */
-    toFlowObject(): FlowNodeSnapshot;
 }

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

@@ -6,8 +6,18 @@
  *
  */
 import { ICEGroup } from '../ice-render/index';
-/** 流程图节点类型：起止 / 处理 / 判定 / 输入输出 */
-export declare type FlowNodeKind = 'terminator' | 'process' | 'decision' | 'io';
+/**
+ * 节点类型词汇表。
+ *
+ * - 流程图：`terminator` / `process` / `decision` / `io`
+ * - BPMN 2.0：`bpmnEvent` / `bpmnTask` / `bpmnGateway` / `bpmnSubprocess` /
+ *   `bpmnDataObject` / `bpmnAnnotation` / `bpmnPool` / `bpmnLane`
+ *
+ * BPMN 复用同一套节点/连线/历史/快照机制（都是 `FlowNode`），语义差异由 `kind`
+ * 与 BPMN 专属属性（eventKind / trigger / gatewayType / taskType / band）承载，
+ * 因此文档、React 绑定、DSL 都不需要第二套实现。
+ */
+export declare type FlowNodeKind = 'terminator' | 'process' | 'decision' | 'io' | 'bpmnEvent' | 'bpmnTask' | 'bpmnGateway' | 'bpmnSubprocess' | 'bpmnDataObject' | 'bpmnAnnotation' | 'bpmnPool' | 'bpmnLane';
 export declare type FlowNodePreset = {
     label: string;
     width: number;
@@ -15,23 +25,28 @@ export declare type FlowNodePreset = {
     fill: string;
     stroke: string;
     radius?: number;
-    shape: 'rect' | 'diamond' | 'parallelogram';
+    shape: 'rect' | 'diamond' | 'parallelogram' | 'event' | 'gateway' | 'dataObject' | 'annotation' | 'lane';
+    /** 外框线宽（BPMN 结束事件用粗圈） */
+    lineWidth?: number;
+    /** 虚线（注释框） */
+    lineDash?: number[];
+    /** 名称带：泳道在左、池在顶 */
+    band?: 'left' | 'top';
+    bandSize?: number;
+    /** 标题摆放：居中（图元）或左上（池/泳道/注释） */
+    labelPlacement?: 'center' | 'top-left';
+    /** 背景透明（泳道用：相邻泳道共享边界时，填充会盖住邻居的边框） */
+    transparent?: boolean;
+    /** 默认的任务类型角标（bpmnTask 用） */
+    taskType?: string;
+    /** 默认事件种类 / 触发（bpmnEvent 用） */
+    eventKind?: string;
+    trigger?: string;
+    /** 默认网关类型（bpmnGateway 用） */
+    gatewayType?: string;
 };
 /** 各类型节点的默认尺寸与配色（同时作为属性面板的预设） */
 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 +59,23 @@ export default class FlowNode extends ICEGroup {
     static readonly typeId = "FlowNode";
     protected shapeComponent: any;
     protected labelComponent: any;
+    /** BPMN 装饰件（任务角标 / 子流程标记），随形状一起重建 */
+    protected decorationComponents: any[];
+    /**
+     * 内部子组件（形状 + 标题）由 kind/尺寸/配色派生，构造函数会重建 →
+     * 不参与引擎序列化（否则往返会重复挂载，且子组件 zIndex 抖动，见 ICEComponent.hasDerivedChildren）。
+     */
+    hasDerivedChildren(): boolean;
     constructor(props?: any);
     /** 按当前 kind / 尺寸 / 配色重建形状与标题（切换类型或改样式时调用） */
     private __buildShape;
+    /**
+     * BPMN 装饰件（任务类型角标、子流程折叠标记）。
+     *
+     * 它们与形状/标题一样由节点 state 派生，因此不需要单独序列化
+     * （见 hasDerivedChildren：整个内部子树都是派生的）。
+     */
+    private __buildDecorations;
     /** 改节点属性（标题 / 类型 / 配色 / 尺寸），必要时重建形状 */
     applyPatch(patch?: Record<string, any>): this;
-    /** 流程快照用的纯数据 */
-    toFlowObject(): FlowNodeSnapshot;
 }

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

@@ -10,14 +10,6 @@ import EventBus from '../event/EventBus.mjs';
 import ICEEventTarget from '../event/ICEEventTarget.mjs';
 import ICEBoundingBox from '../geometry/ICEBoundingBox.mjs';
 import ICE from '../ICE.mjs';
-/**
- * @class ICEComponent
- *
- * 最顶级的抽象类，Canvas 内部所有可见的组件都是它的子类。
- *
- * @abstract
- * @author 大漠穷秋<damoqiongqiu@126.com>
- */
 declare abstract class ICEComponent extends ICEEventTarget {
     ice: ICE;
     root: any;
@@ -337,6 +329,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

@@ -10,14 +10,6 @@ import EventBus from '../event/EventBus';
 import ICEEventTarget from '../event/ICEEventTarget';
 import ICEBoundingBox from '../geometry/ICEBoundingBox';
 import ICE from '../ICE';
-/**
- * @class ICEComponent
- *
- * 最顶级的抽象类，Canvas 内部所有可见的组件都是它的子类。
- *
- * @abstract
- * @author 大漠穷秋<damoqiongqiu@126.com>
- */
 declare abstract class ICEComponent extends ICEEventTarget {
     ice: ICE;
     root: any;
@@ -337,6 +329,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/container/ICEGroup.d.mts

@@ -79,6 +79,16 @@ declare class ICEGroup extends ICERect {
      */
     addChild(child: ICEComponent, markDirty?: boolean): void;
     addChildren(arr: Array<ICEComponent>): void;
+    /**
+     * 把某个组件迁移到本容器下（**不销毁**它）。
+     *
+     * 为什么需要单独的 API：`removeChild()` 末尾会调用 `child.destory()`（清事件、清子节点），
+     * 所以「先 removeChild 再 addChild」式的重父级会把组件连同内部子树一起毁掉
+     * （BPMN 池/泳道里嵌节点时就踩到这个坑：标题、角标全没了）。
+     * 本方法只从旧父级的 childNodes / 去重集合里摘除，再挂到本容器，组件本体与子树保持完好。
+     * **坐标不换算**：调用方若要保持世界位置，请自行换算 left/top。
+     */
+    adoptChild(child: ICEComponent, markDirty?: boolean): void;
     removeChild(child: ICEComponent, markDirty?: boolean): void;
     removeChildren(arr: Array<ICEComponent>): void;
     /**

package/dist/types/ice-render/graphic/container/ICEGroup.d.ts

@@ -79,6 +79,16 @@ declare class ICEGroup extends ICERect {
      */
     addChild(child: ICEComponent, markDirty?: boolean): void;
     addChildren(arr: Array<ICEComponent>): void;
+    /**
+     * 把某个组件迁移到本容器下（**不销毁**它）。
+     *
+     * 为什么需要单独的 API：`removeChild()` 末尾会调用 `child.destory()`（清事件、清子节点），
+     * 所以「先 removeChild 再 addChild」式的重父级会把组件连同内部子树一起毁掉
+     * （BPMN 池/泳道里嵌节点时就踩到这个坑：标题、角标全没了）。
+     * 本方法只从旧父级的 childNodes / 去重集合里摘除，再挂到本容器，组件本体与子树保持完好。
+     * **坐标不换算**：调用方若要保持世界位置，请自行换算 left/top。
+     */
+    adoptChild(child: ICEComponent, markDirty?: boolean): void;
     removeChild(child: ICEComponent, markDirty?: boolean): void;
     removeChildren(arr: Array<ICEComponent>): void;
     /**

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,12 +14,17 @@ 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';
+export { default as BpmnDesigner } from './bpmn/BpmnDesigner.mjs';
+export { validateBpmn } from './bpmn/bpmn_validate.mjs';
+export type { BpmnIssue } from './bpmn/bpmn_validate.mjs';
+export { toBpmnXml, fromBpmnXml } from './bpmn/bpmn_xml.mjs';
+export type { BpmnImportResult } from './bpmn/bpmn_xml.mjs';
 /**
  * 引擎内核（ice-render）在构建时已被打包进本包，这里一并导出。
  *

package/dist/types/index.d.ts

@@ -14,12 +14,17 @@ 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';
+export { default as BpmnDesigner } from './bpmn/BpmnDesigner';
+export { validateBpmn } from './bpmn/bpmn_validate';
+export type { BpmnIssue } from './bpmn/bpmn_validate';
+export { toBpmnXml, fromBpmnXml } from './bpmn/bpmn_xml';
+export type { BpmnImportResult } from './bpmn/bpmn_xml';
 /**
  * 引擎内核（ice-render）在构建时已被打包进本包，这里一并导出。
  *

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;

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

@@ -1,4 +1,4 @@
-import { EntityDesigner } from '../index';
+import { EntityDesigner, FlowDesigner } from '../index';
 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;

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

@@ -1,7 +1,7 @@
 /**
  * React 绑定层的类型定义。
  */
-import type { EntityDesigner, ProjectLoadReport } from '../index.mjs';
+import type { EntityDesigner, FlowDesigner, FlowLoadReport, FlowNodeKind, ProjectLoadReport } from '../index.mjs';
 export declare type EntityDesignerChangePayload = {
     /** 项目快照，等价于 designer.serializeProject() 的结果 */
     snapshot: string;
@@ -62,3 +62,61 @@ export declare type EntityDesignerCanvasProps = {
     /** 子节点渲染在上下文内部，可直接使用 useEntityDesigner() */
     children?: any;
 };
+export declare type FlowDesignerChangePayload = {
+    /** 流程图快照，等价于 designer.serialize() 的结果 */
+    snapshot: string;
+    /** 当前节点 / 连线条数，便于直接渲染统计信息 */
+    counts: {
+        nodes: number;
+        edges: number;
+    };
+};
+export declare type FlowDesignerHandle = {
+    /** 底层 ICE 实例（卸载后为 null） */
+    ice: any;
+    /** 底层 FlowDesigner 实例（卸载后为 null） */
+    designer: FlowDesigner | null;
+    addNode(kind: FlowNodeKind, props?: any): any;
+    connect(props: any): any;
+    updateNode(id: string, patch: any): any;
+    updateEdge(id: string, patch: any): any;
+    remove(id: string): void;
+    load(json: string): FlowLoadReport;
+    undo(): void;
+    redo(): void;
+    serialize(): string;
+    toSnapshot(): any;
+    fitViewport(padding?: number): void;
+};
+export declare type FlowDesignerCanvasProps = {
+    /**
+     * 受控模式：流程图快照。变化时会同步进画布（内部变更通过 onChange 上报，带循环保护）。
+     * 与 defaultValue 互斥，value 优先。
+     */
+    value?: string;
+    /** 非受控模式：初始流程图快照（等价于 load(defaultValue)） */
+    defaultValue?: string;
+    /** 渲染模式，默认 dirty-rect */
+    renderMode?: 'dirty-rect' | 'full';
+    /**
+     * 流程变更回调（建节点 / 连线 / 改属性 / 画布拖动 / 载入 / undo / redo 之后触发）。
+     * 注意：画布上拖动节点也会触发（FlowDesigner 订阅了引擎的 BEFORE_MOVE / AFTER_MOVE），
+     * 因此依赖它的自动保存能拿到拖拽后的最新坐标。
+     */
+    onChange?: (payload: FlowDesignerChangePayload) => void;
+    /**
+     * 快照载入失败回调（非法 / 结构不合法）。不传时默认 console.error；
+     * 组件内部已捕获，不会把错误抛进 React 渲染树。
+     */
+    onError?: (payload: EntityDesignerErrorPayload) => void;
+    /** 实例就绪回调，回调里拿到命令式句柄 */
+    onReady?: (handle: FlowDesignerHandle) => void;
+    className?: string;
+    /** 容器内联样式（与 width/height 合并） */
+    style?: any;
+    /** 画布宽高（像素），同时作为容器尺寸，默认 1200 x 800 */
+    width?: number;
+    height?: number;
+    /** 子节点渲染在上下文内部，可直接使用 useFlowDesigner() */
+    children?: any;
+};