ice-entity-designer 0.0.20 → 0.0.22

package/dist/types/bpmn/BpmnDesigner.d.mts

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ *
+ */
+import FlowDesigner from '../flow/FlowDesigner.mjs';
+import type { BpmnIssue } from './bpmn_validate.mjs';
+/**
+ * BPMN 设计器：`FlowDesigner` 的薄扩展，只补两件 BPMN 特有的事：
+ *
+ * 1. **顺序流上的条件/默认标记**（BPMN 记法要求）：标记是「派生装饰」，
+ *    放在 `ice.toolNodes`（工具层）里 —— 工具层不参与引擎序列化（我们上轮验证过），
+ *    所以文档仍然是纯粹的业务模型，标记由 `flowType/condition/isDefault` 推出来。
+ * 2. **BPMN 语义校验**：`validate()` 直接复用 `validateBpmn()`。
+ *
+ * 其余能力（建节点/连线、选择、增删改、撤销重做、快照存取、适应视图、订阅）
+ * 全部继承自 `FlowDesigner` —— 沿用同一套机制，不再造第二份。
+ */
+export default class BpmnDesigner extends FlowDesigner {
+    private __markers;
+    private __markerSyncing;
+    private __nesting;
+    constructor(ice: any);
+    /** BPMN 语义校验（事件/网关/池/连通性等，见 bpmn_validate.ts） */
+    validateBpmn(): BpmnIssue[];
+    /**
+     * 建节点：除常规流程元素外，**自动按几何把节点嵌进池/泳道**（用引擎的容器能力）。
+     *
+     * 为什么要真嵌套：外层容器（池）被拖动时，引擎的矩阵组合会让内部泳道与泳道里的节点
+     * 一起移动 —— 这正是「拖动池子，里面的东西跟着走」的正确实现；扁平结构做不到。
+     *
+     * 归属规则：取「面积最小的、包住节点中心的容器」（泳道比池小 → 优先落在泳道里）。
+     * 子组件坐标是**父容器左上角**为原点，因此嵌套时要做一次坐标换算。
+     */
+    createNode(kind: any, props?: any): any;
+    /** 把（已经在 ice 根上的）节点嵌进最内层容器 */
+    private __nestByGeometry;
+    /**
+     * 容器的**内容区**（扣掉名称带）。
+     *
+     * 池的名称带在顶部、泳道在左侧，名称带属于标题区、不该被内部元素压住；
+     * 所以归属判定按内容区算，否则泳道会盖住池标题。
+     */
+    private __contentBox;
+    /** 顺序流的条件/默认标记：按需创建、原位更新（放在工具层，不污染文档） */
+    syncFlowMarkers(): void;
+    dispose(): void;
+}

package/dist/types/bpmn/BpmnDesigner.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ *
+ */
+import FlowDesigner from '../flow/FlowDesigner';
+import type { BpmnIssue } from './bpmn_validate';
+/**
+ * BPMN 设计器：`FlowDesigner` 的薄扩展，只补两件 BPMN 特有的事：
+ *
+ * 1. **顺序流上的条件/默认标记**（BPMN 记法要求）：标记是「派生装饰」，
+ *    放在 `ice.toolNodes`（工具层）里 —— 工具层不参与引擎序列化（我们上轮验证过），
+ *    所以文档仍然是纯粹的业务模型，标记由 `flowType/condition/isDefault` 推出来。
+ * 2. **BPMN 语义校验**：`validate()` 直接复用 `validateBpmn()`。
+ *
+ * 其余能力（建节点/连线、选择、增删改、撤销重做、快照存取、适应视图、订阅）
+ * 全部继承自 `FlowDesigner` —— 沿用同一套机制，不再造第二份。
+ */
+export default class BpmnDesigner extends FlowDesigner {
+    private __markers;
+    private __markerSyncing;
+    private __nesting;
+    constructor(ice: any);
+    /** BPMN 语义校验（事件/网关/池/连通性等，见 bpmn_validate.ts） */
+    validateBpmn(): BpmnIssue[];
+    /**
+     * 建节点：除常规流程元素外，**自动按几何把节点嵌进池/泳道**（用引擎的容器能力）。
+     *
+     * 为什么要真嵌套：外层容器（池）被拖动时，引擎的矩阵组合会让内部泳道与泳道里的节点
+     * 一起移动 —— 这正是「拖动池子，里面的东西跟着走」的正确实现；扁平结构做不到。
+     *
+     * 归属规则：取「面积最小的、包住节点中心的容器」（泳道比池小 → 优先落在泳道里）。
+     * 子组件坐标是**父容器左上角**为原点，因此嵌套时要做一次坐标换算。
+     */
+    createNode(kind: any, props?: any): any;
+    /** 把（已经在 ice 根上的）节点嵌进最内层容器 */
+    private __nestByGeometry;
+    /**
+     * 容器的**内容区**（扣掉名称带）。
+     *
+     * 池的名称带在顶部、泳道在左侧，名称带属于标题区、不该被内部元素压住；
+     * 所以归属判定按内容区算，否则泳道会盖住池标题。
+     */
+    private __contentBox;
+    /** 顺序流的条件/默认标记：按需创建、原位更新（放在工具层，不污染文档） */
+    syncFlowMarkers(): void;
+    dispose(): void;
+}

package/dist/types/bpmn/bpmn_shapes.d.mts

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ *
+ */
+import { ICEPath } from '../ice-render/index.mjs';
+/**
+ * 事件（圆）：开始 / 中间 / 结束 + 触发类型图标。
+ *
+ * state.eventKind: 'start' | 'intermediate' | 'end'
+ * state.trigger:   'none' | 'message' | 'timer' | 'error' | 'terminate'
+ */
+export declare class BpmnEventShape extends ICEPath {
+    static readonly typeId = "BpmnEventShape";
+    protected createPathObject(): any;
+}
+/** 网关（菱形 + 内部符号）：排他 × / 并行 + / 包容 ○ / 事件网关（五边形） */
+export declare class BpmnGatewayShape extends ICEPath {
+    static readonly typeId = "BpmnGatewayShape";
+    protected createPathObject(): any;
+}
+/** 任务类型角标（左上角小图标，尺寸固定 12×12，由节点定位） */
+export declare class BpmnTaskIcon extends ICEPath {
+    static readonly typeId = "BpmnTaskIcon";
+    protected createPathObject(): any;
+}
+/** 子流程折叠标记（底部居中的「+」小方块） */
+export declare class BpmnSubprocessMarker extends ICEPath {
+    static readonly typeId = "BpmnSubprocessMarker";
+    protected createPathObject(): any;
+}
+/** 数据对象：右上角折角矩形 */
+export declare class BpmnDataObjectShape extends ICEPath {
+    static readonly typeId = "BpmnDataObjectShape";
+    protected createPathObject(): any;
+}
+/**
+ * 文本注释：**完整矩形** + 左侧内嵌的括号竖线（bpmn.io / Camunda 的标准画法）。
+ *
+ * 曾经画成「左括号 + 上下两条线、右侧开口」—— 那样右侧没有边框，看起来像个残缺的框；
+ * BPMN 2.0 的文本注释是闭合矩形，左侧竖线只是括号装饰，四条边都要有。
+ */
+export declare class BpmnAnnotationShape extends ICEPath {
+    static readonly typeId = "BpmnAnnotationShape";
+    protected createPathObject(): any;
+}
+/**
+ * 泳道 / 池：矩形 + 名称带分隔线。
+ * `band` = 'left'（横向泳道，默认）| 'top'（池标题带）
+ */
+export declare class BpmnLaneShape extends ICEPath {
+    static readonly typeId = "BpmnLaneShape";
+    protected createPathObject(): any;
+}
+/** 顺序流上的条件/默认标记（小菱形 / 斜杠），尺寸固定 14×14 */
+export declare class BpmnFlowMarker extends ICEPath {
+    static readonly typeId = "BpmnFlowMarker";
+    protected createPathObject(): any;
+}

package/dist/types/bpmn/bpmn_shapes.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ *
+ */
+import { ICEPath } from '../ice-render/index';
+/**
+ * 事件（圆）：开始 / 中间 / 结束 + 触发类型图标。
+ *
+ * state.eventKind: 'start' | 'intermediate' | 'end'
+ * state.trigger:   'none' | 'message' | 'timer' | 'error' | 'terminate'
+ */
+export declare class BpmnEventShape extends ICEPath {
+    static readonly typeId = "BpmnEventShape";
+    protected createPathObject(): any;
+}
+/** 网关（菱形 + 内部符号）：排他 × / 并行 + / 包容 ○ / 事件网关（五边形） */
+export declare class BpmnGatewayShape extends ICEPath {
+    static readonly typeId = "BpmnGatewayShape";
+    protected createPathObject(): any;
+}
+/** 任务类型角标（左上角小图标，尺寸固定 12×12，由节点定位） */
+export declare class BpmnTaskIcon extends ICEPath {
+    static readonly typeId = "BpmnTaskIcon";
+    protected createPathObject(): any;
+}
+/** 子流程折叠标记（底部居中的「+」小方块） */
+export declare class BpmnSubprocessMarker extends ICEPath {
+    static readonly typeId = "BpmnSubprocessMarker";
+    protected createPathObject(): any;
+}
+/** 数据对象：右上角折角矩形 */
+export declare class BpmnDataObjectShape extends ICEPath {
+    static readonly typeId = "BpmnDataObjectShape";
+    protected createPathObject(): any;
+}
+/**
+ * 文本注释：**完整矩形** + 左侧内嵌的括号竖线（bpmn.io / Camunda 的标准画法）。
+ *
+ * 曾经画成「左括号 + 上下两条线、右侧开口」—— 那样右侧没有边框，看起来像个残缺的框；
+ * BPMN 2.0 的文本注释是闭合矩形，左侧竖线只是括号装饰，四条边都要有。
+ */
+export declare class BpmnAnnotationShape extends ICEPath {
+    static readonly typeId = "BpmnAnnotationShape";
+    protected createPathObject(): any;
+}
+/**
+ * 泳道 / 池：矩形 + 名称带分隔线。
+ * `band` = 'left'（横向泳道，默认）| 'top'（池标题带）
+ */
+export declare class BpmnLaneShape extends ICEPath {
+    static readonly typeId = "BpmnLaneShape";
+    protected createPathObject(): any;
+}
+/** 顺序流上的条件/默认标记（小菱形 / 斜杠），尺寸固定 14×14 */
+export declare class BpmnFlowMarker extends ICEPath {
+    static readonly typeId = "BpmnFlowMarker";
+    protected createPathObject(): any;
+}

package/dist/types/bpmn/bpmn_validate.d.mts

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ *
+ */
+/**
+ * BPMN 2.0 语义校验（记法之外的那一层）。
+ *
+ * 只做「结构正确性」检查，不涉及具体引擎的扩展属性；返回问题列表供属性面板/工具条展示。
+ * 与 ER 侧的 `validateSchema()` 同一形态（`{ level, code, message, componentId }`）。
+ *
+ * 约定：**容器归属按几何判定**——节点落在哪个池/泳道矩形内就属于它。
+ * （真实 BPMN 里泳道是 `<laneSet>` 的显式归属；我们不做重父级，导出 XML 时按几何归类，
+ * 这样拖拽体验与文档模型都简单，且不会出现「跨容器拖动导致连线错乱」。）
+ */
+export declare type BpmnIssue = {
+    level: 'error' | 'warning';
+    code: string;
+    message: string;
+    componentId?: string;
+};
+export declare function validateBpmn(designer: any): BpmnIssue[];

package/dist/types/bpmn/bpmn_validate.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ *
+ */
+/**
+ * BPMN 2.0 语义校验（记法之外的那一层）。
+ *
+ * 只做「结构正确性」检查，不涉及具体引擎的扩展属性；返回问题列表供属性面板/工具条展示。
+ * 与 ER 侧的 `validateSchema()` 同一形态（`{ level, code, message, componentId }`）。
+ *
+ * 约定：**容器归属按几何判定**——节点落在哪个池/泳道矩形内就属于它。
+ * （真实 BPMN 里泳道是 `<laneSet>` 的显式归属；我们不做重父级，导出 XML 时按几何归类，
+ * 这样拖拽体验与文档模型都简单，且不会出现「跨容器拖动导致连线错乱」。）
+ */
+export declare type BpmnIssue = {
+    level: 'error' | 'warning';
+    code: string;
+    message: string;
+    componentId?: string;
+};
+export declare function validateBpmn(designer: any): BpmnIssue[];

package/dist/types/bpmn/bpmn_xml.d.mts

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ *
+ */
+/**
+ * BPMN 2.0 XML 互操作（`<definitions>` / `<process>` / `<collaboration>` / DI 布局）。
+ *
+ * 覆盖范围（与我们支持的元素一一对应，够和 Camunda / Flowable / bpmn.io 互通）：
+ * - 协作：`<collaboration><participant>`（池）、`<laneSet><lane>`（泳道）、`<messageFlow>`
+ * - 流程：`<startEvent>` / `<endEvent>` / `<intermediateThrowEvent>`、`<task>`（含
+ *   `userTask` / `serviceTask` / `scriptTask` / `sendTask` / `receiveTask` / `manualTask`）、
+ *   `<exclusiveGateway>` / `<parallelGateway>` / `<inclusiveGateway>` / `<eventBasedGateway>`、
+ *   `<subProcess>`、`<dataObjectReference>`、`<textAnnotation>`
+ * - 连线：`<sequenceFlow>`（带 `<conditionExpression>` 与 `default` 属性）、`<messageFlow>`、
+ *   `<association>`
+ * - 图形：`<bpmndi:BPMNDiagram><bpmndi:BPMNPlane>` + `<bpmndi:BPMNShape><dc:Bounds>` /
+ *   `<bpmndi:BPMNEdge><di:waypoint>`
+ *
+ * 未识别的元素/属性会被忽略（导入时计入 `warnings`），不会让整份文件打不开 ——
+ * 与引擎 `Deserializer` 的容错语义保持一致。
+ */
+import type FlowDesigner from '../flow/FlowDesigner.mjs';
+export declare type BpmnImportResult = {
+    nodes: number;
+    edges: number;
+    warnings: string[];
+};
+/**
+ * 导出 BPMN 2.0 XML。
+ *
+ * 容器归属按几何判定：节点落在哪个池矩形内就归到该池的 `<process>`；
+ * 池与池之间的连线导出为 `<messageFlow>`（并放进 `<collaboration>`），
+ * 池内部的顺序流导出为该 process 的 `<sequenceFlow>`。
+ */
+export declare function toBpmnXml(designer: FlowDesigner, options?: {
+    name?: string;
+}): string;
+/**
+ * 导入 BPMN 2.0 XML（覆盖范围见文件头注释）。
+ *
+ * 需要 `DOMParser`（浏览器 / jsdom 提供）。无法识别的元素会被忽略并计入 `warnings`。
+ */
+export declare function fromBpmnXml(xml: string, designer: FlowDesigner): BpmnImportResult;

package/dist/types/bpmn/bpmn_xml.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ *
+ */
+/**
+ * BPMN 2.0 XML 互操作（`<definitions>` / `<process>` / `<collaboration>` / DI 布局）。
+ *
+ * 覆盖范围（与我们支持的元素一一对应，够和 Camunda / Flowable / bpmn.io 互通）：
+ * - 协作：`<collaboration><participant>`（池）、`<laneSet><lane>`（泳道）、`<messageFlow>`
+ * - 流程：`<startEvent>` / `<endEvent>` / `<intermediateThrowEvent>`、`<task>`（含
+ *   `userTask` / `serviceTask` / `scriptTask` / `sendTask` / `receiveTask` / `manualTask`）、
+ *   `<exclusiveGateway>` / `<parallelGateway>` / `<inclusiveGateway>` / `<eventBasedGateway>`、
+ *   `<subProcess>`、`<dataObjectReference>`、`<textAnnotation>`
+ * - 连线：`<sequenceFlow>`（带 `<conditionExpression>` 与 `default` 属性）、`<messageFlow>`、
+ *   `<association>`
+ * - 图形：`<bpmndi:BPMNDiagram><bpmndi:BPMNPlane>` + `<bpmndi:BPMNShape><dc:Bounds>` /
+ *   `<bpmndi:BPMNEdge><di:waypoint>`
+ *
+ * 未识别的元素/属性会被忽略（导入时计入 `warnings`），不会让整份文件打不开 ——
+ * 与引擎 `Deserializer` 的容错语义保持一致。
+ */
+import type FlowDesigner from '../flow/FlowDesigner';
+export declare type BpmnImportResult = {
+    nodes: number;
+    edges: number;
+    warnings: string[];
+};
+/**
+ * 导出 BPMN 2.0 XML。
+ *
+ * 容器归属按几何判定：节点落在哪个池矩形内就归到该池的 `<process>`；
+ * 池与池之间的连线导出为 `<messageFlow>`（并放进 `<collaboration>`），
+ * 池内部的顺序流导出为该 process 的 `<sequenceFlow>`。
+ */
+export declare function toBpmnXml(designer: FlowDesigner, options?: {
+    name?: string;
+}): string;
+/**
+ * 导入 BPMN 2.0 XML（覆盖范围见文件头注释）。
+ *
+ * 需要 `DOMParser`（浏览器 / jsdom 提供）。无法识别的元素会被忽略并计入 `warnings`。
+ */
+export declare function fromBpmnXml(xml: string, designer: FlowDesigner): BpmnImportResult;

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 = {
@@ -67,6 +68,13 @@ export default class FlowDesigner {
     constructor(ice: ICE);
     get nodes(): any[];
     get edges(): any[];
+    /**
+     * 递归展开场景树（容器型节点 —— 如 BPMN 的池/泳道 —— 里面的子节点同样算流程的一部分）。
+     *
+     * 扁平场景（纯流程图/ER）与旧行为完全一致；嵌套场景下 nodes/edges 才看得到后代节点，
+     * 校验、统计、快照、连线端点查找都因此无需特判。
+     */
+    protected __flatten(): any[];
     get selected(): any;
     /**
      * 订阅流程变更（增删改 / 连线 / 载入 / undo / redo 之后触发）。
@@ -94,13 +102,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 = {
@@ -67,6 +68,13 @@ export default class FlowDesigner {
     constructor(ice: ICE);
     get nodes(): any[];
     get edges(): any[];
+    /**
+     * 递归展开场景树（容器型节点 —— 如 BPMN 的池/泳道 —— 里面的子节点同样算流程的一部分）。
+     *
+     * 扁平场景（纯流程图/ER）与旧行为完全一致；嵌套场景下 nodes/edges 才看得到后代节点，
+     * 校验、统计、快照、连线端点查找都因此无需特判。
+     */
+    protected __flatten(): any[];
     get selected(): any;
     /**
      * 订阅流程变更（增删改 / 连线 / 载入 / undo / redo 之后触发）。
@@ -94,13 +102,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,15 @@ export declare type FlowEdgeSnapshot = {
  */
 export default class FlowEdge extends ICEVisioLink {
     static readonly typeId = "FlowEdge";
+    /** 连线没有子组件；声明派生可保证将来即使加了内部装饰也不会被重复序列化 */
+    hasDerivedChildren(): boolean;
     constructor(props?: any);
-    /** 流程快照用的纯数据 */
-    toFlowObject(): FlowEdgeSnapshot;
+    /**
+     * 改连线属性，并按 BPMN 语义重算派生样式（线型 / 虚线 / 箭头）。
+     *
+     * - sequence：实线 + 实心箭头
+     * - message：虚线 + 空心箭头（跨参与者通信）
+     * - association：点线 + 无箭头
+     */
+    applyPatch(patch?: Record<string, any>): this;
 }

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,15 @@ export declare type FlowEdgeSnapshot = {
  */
 export default class FlowEdge extends ICEVisioLink {
     static readonly typeId = "FlowEdge";
+    /** 连线没有子组件；声明派生可保证将来即使加了内部装饰也不会被重复序列化 */
+    hasDerivedChildren(): boolean;
     constructor(props?: any);
-    /** 流程快照用的纯数据 */
-    toFlowObject(): FlowEdgeSnapshot;
+    /**
+     * 改连线属性，并按 BPMN 语义重算派生样式（线型 / 虚线 / 箭头）。
+     *
+     * - sequence：实线 + 实心箭头
+     * - message：虚线 + 空心箭头（跨参与者通信）
+     * - association：点线 + 无箭头
+     */
+    applyPatch(patch?: Record<string, any>): this;
 }