ice-entity-designer 0.10.0 → 0.12.0

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

@@ -54,6 +54,21 @@ export default class FlowDesigner {
     private __redoStack;
     private __historyEnabled;
     private __maxHistory;
+    /**
+     * 历史栈**按留存字节**的封顶（默认 32 MB）。
+     *
+     * 为什么不能只按条数封顶：历史里存的是**整份文档快照**，而快照大小随文档规模涨 ——
+     * 真机实测（2026-09-21，水务编辑器用本应用 API 造 2,020 个符号 + 2,020 条管线）：
+     * 100 条快照 ≈ **874 MB**（编辑器堆 932.8 MB 里 94% 是它），`resetHistory()` 之后只剩 58.4 MB。
+     * 按字节封顶后：小文档仍然能撤销很多步（条数上限照旧 100），大文档则自动收敛到几十步 ——
+     * 用户能感知的是"撤销变浅了一点"，而不是"标签页吃掉 1 GB"。
+     */
+    private __maxHistoryBytes;
+    /** undo / redo 两栈里**留存的字符串字节数**（快照是字符串，长度即字节量级）。 */
+    private __historyBytes;
+    /** 批量改动嵌套深度（见 `beginBatch`）：>0 时批内不记历史，批末统一记"批前状态"。 */
+    private __batchDepth;
+    private __batchStart;
     private __listeners;
     private __mousedownHandler;
     /** 画布拖拽节点时会话：BEFORE_MOVE 记一次历史，mouseup 结束会话 */
@@ -91,6 +106,19 @@ export default class FlowDesigner {
     constructor(ice: ICE);
     get nodes(): any[];
     get edges(): any[];
+    /**
+     * 判"这是不是本设计器认的**节点** / **连线**"（选中、更新、删除、快照收集都用它）。
+     *
+     * 默认认 `FlowNode` / `FlowEdge`**及其子类**；**不是它们分支的领域图元**要在子类里覆盖
+     * （水务的 `WaterSymbol extends ICEGroup`、`WaterPipe extends FlowEdge` 就是这种情况，
+     * 见 `WaterProcessDesigner`）。
+     *
+     * 2026-09-21 修：原先这些地方比的是**精确 `typeId`**，于是领域图元在
+     * 「点选 / `updateNode` / `updateEdge`」四处**静默失效**（不报错、只是没反应）——
+     * 实测既有 `water-editor.html` 点符号选不中就是这个根因。
+     */
+    protected isNodeComponent(component: any): boolean;
+    protected isEdgeComponent(component: any): boolean;
     /**
      * 递归展开场景树（容器型节点 —— 如 BPMN 的池/泳道 —— 里面的子节点同样算流程的一部分）。
      *
@@ -258,7 +286,47 @@ export default class FlowDesigner {
     captureHistory(): void;
     /** 清空撤销/重做栈（用于「载入示例」这类不该占用历史的初始化操作） */
     resetHistory(): void;
+    /**
+     * **批量改动**：批内不逐条记历史，整批算**一条**（撤销时整批回退）。
+     *
+     * 什么时候用：程序化建图 / 导入 / 一次性铺一批图元。不用它的话每个图元都会
+     * **整份序列化一次**，实测 2,020 个符号花 **58.5 秒**（≈29 ms/个），历史里还留下 100 份大快照。
+     *
+     * ```ts
+     * designer.beginBatch();
+     * for (const item of docs) designer.createSymbol(...);
+     * designer.endBatch();
+     * ```
+     */
+    beginBatch(): void;
+    endBatch(): void;
+    /**
+     * **历史预算**（给宿主 / 测试用）：条数上限与**留存字节**上限。
+     *
+     * 默认 100 条 / 32 MB。大文档（几万个图元）下快照很大，字节上限会先把老条目挤掉 ——
+     * 这是刻意的取舍：宁可"撤销浅一点"，也不要"标签页吃掉 1 GB"（实测 2,020 符号 × 100 条 = 874 MB）。
+     */
+    setHistoryBudget(budget?: {
+        maxEntries?: number;
+        maxBytes?: number;
+    }): void;
+    /** 当前历史占用的规模（诊断 / 断言用）：`{ undo, redo, bytes }`。 */
+    getHistoryStats(): {
+        undo: number;
+        redo: number;
+        bytes: number;
+    };
     protected __captureHistory(): void;
+    /** 入栈 + 双重封顶（条数 + 留存字节）+ 清空 redo。 */
+    private __pushHistory;
+    /**
+     * 重算两栈的留存字节。
+     *
+     * 为什么"重算"而不是"加减"：`undo` / `redo` 里快照在两栈之间搬家，还有回放失败的回滚分支 ——
+     * 加减法只要漏一条分支就会越记越偏，而重算是 O(栈深) 的字符串长度求和（≤100 条），
+     * 属于"慢一点但永远对"的那一类。这个量只用于**封顶判断**，不进任何热路径（每帧）。
+     */
+    private __recountHistory;
     private __applySnapshot;
     /**
      * 撤销：先记账（把当前状态压入 redo、从 undo 弹出目标），再回放目标快照，
@@ -268,5 +336,12 @@ export default class FlowDesigner {
     undo(): void;
     redo(): void;
     private __handleMouseDown;
+    /**
+     * 这个组件算不算"可以被点选的领域图元"（选中判据的唯一入口，领域包可覆盖）。
+     *
+     * 默认认 `FlowNode` / `FlowEdge` 及其子类；**不是它们分支的领域图元**要在子类里补
+     * （水务的 `WaterSymbol extends ICEGroup`、`WaterPipe extends FlowEdge` 就是这么回事）。
+     */
+    protected isSelectableComponent(component: any): boolean;
     dispose(): void;
 }

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

@@ -54,6 +54,21 @@ export default class FlowDesigner {
     private __redoStack;
     private __historyEnabled;
     private __maxHistory;
+    /**
+     * 历史栈**按留存字节**的封顶（默认 32 MB）。
+     *
+     * 为什么不能只按条数封顶：历史里存的是**整份文档快照**，而快照大小随文档规模涨 ——
+     * 真机实测（2026-09-21，水务编辑器用本应用 API 造 2,020 个符号 + 2,020 条管线）：
+     * 100 条快照 ≈ **874 MB**（编辑器堆 932.8 MB 里 94% 是它），`resetHistory()` 之后只剩 58.4 MB。
+     * 按字节封顶后：小文档仍然能撤销很多步（条数上限照旧 100），大文档则自动收敛到几十步 ——
+     * 用户能感知的是"撤销变浅了一点"，而不是"标签页吃掉 1 GB"。
+     */
+    private __maxHistoryBytes;
+    /** undo / redo 两栈里**留存的字符串字节数**（快照是字符串，长度即字节量级）。 */
+    private __historyBytes;
+    /** 批量改动嵌套深度（见 `beginBatch`）：>0 时批内不记历史，批末统一记"批前状态"。 */
+    private __batchDepth;
+    private __batchStart;
     private __listeners;
     private __mousedownHandler;
     /** 画布拖拽节点时会话：BEFORE_MOVE 记一次历史，mouseup 结束会话 */
@@ -91,6 +106,19 @@ export default class FlowDesigner {
     constructor(ice: ICE);
     get nodes(): any[];
     get edges(): any[];
+    /**
+     * 判"这是不是本设计器认的**节点** / **连线**"（选中、更新、删除、快照收集都用它）。
+     *
+     * 默认认 `FlowNode` / `FlowEdge`**及其子类**；**不是它们分支的领域图元**要在子类里覆盖
+     * （水务的 `WaterSymbol extends ICEGroup`、`WaterPipe extends FlowEdge` 就是这种情况，
+     * 见 `WaterProcessDesigner`）。
+     *
+     * 2026-09-21 修：原先这些地方比的是**精确 `typeId`**，于是领域图元在
+     * 「点选 / `updateNode` / `updateEdge`」四处**静默失效**（不报错、只是没反应）——
+     * 实测既有 `water-editor.html` 点符号选不中就是这个根因。
+     */
+    protected isNodeComponent(component: any): boolean;
+    protected isEdgeComponent(component: any): boolean;
     /**
      * 递归展开场景树（容器型节点 —— 如 BPMN 的池/泳道 —— 里面的子节点同样算流程的一部分）。
      *
@@ -258,7 +286,47 @@ export default class FlowDesigner {
     captureHistory(): void;
     /** 清空撤销/重做栈（用于「载入示例」这类不该占用历史的初始化操作） */
     resetHistory(): void;
+    /**
+     * **批量改动**：批内不逐条记历史，整批算**一条**（撤销时整批回退）。
+     *
+     * 什么时候用：程序化建图 / 导入 / 一次性铺一批图元。不用它的话每个图元都会
+     * **整份序列化一次**，实测 2,020 个符号花 **58.5 秒**（≈29 ms/个），历史里还留下 100 份大快照。
+     *
+     * ```ts
+     * designer.beginBatch();
+     * for (const item of docs) designer.createSymbol(...);
+     * designer.endBatch();
+     * ```
+     */
+    beginBatch(): void;
+    endBatch(): void;
+    /**
+     * **历史预算**（给宿主 / 测试用）：条数上限与**留存字节**上限。
+     *
+     * 默认 100 条 / 32 MB。大文档（几万个图元）下快照很大，字节上限会先把老条目挤掉 ——
+     * 这是刻意的取舍：宁可"撤销浅一点"，也不要"标签页吃掉 1 GB"（实测 2,020 符号 × 100 条 = 874 MB）。
+     */
+    setHistoryBudget(budget?: {
+        maxEntries?: number;
+        maxBytes?: number;
+    }): void;
+    /** 当前历史占用的规模（诊断 / 断言用）：`{ undo, redo, bytes }`。 */
+    getHistoryStats(): {
+        undo: number;
+        redo: number;
+        bytes: number;
+    };
     protected __captureHistory(): void;
+    /** 入栈 + 双重封顶（条数 + 留存字节）+ 清空 redo。 */
+    private __pushHistory;
+    /**
+     * 重算两栈的留存字节。
+     *
+     * 为什么"重算"而不是"加减"：`undo` / `redo` 里快照在两栈之间搬家，还有回放失败的回滚分支 ——
+     * 加减法只要漏一条分支就会越记越偏，而重算是 O(栈深) 的字符串长度求和（≤100 条），
+     * 属于"慢一点但永远对"的那一类。这个量只用于**封顶判断**，不进任何热路径（每帧）。
+     */
+    private __recountHistory;
     private __applySnapshot;
     /**
      * 撤销：先记账（把当前状态压入 redo、从 undo 弹出目标），再回放目标快照，
@@ -268,5 +336,12 @@ export default class FlowDesigner {
     undo(): void;
     redo(): void;
     private __handleMouseDown;
+    /**
+     * 这个组件算不算"可以被点选的领域图元"（选中判据的唯一入口，领域包可覆盖）。
+     *
+     * 默认认 `FlowNode` / `FlowEdge` 及其子类；**不是它们分支的领域图元**要在子类里补
+     * （水务的 `WaterSymbol extends ICEGroup`、`WaterPipe extends FlowEdge` 就是这么回事）。
+     */
+    protected isSelectableComponent(component: any): boolean;
     dispose(): void;
 }

package/dist/types/index.d.mts

@@ -79,3 +79,5 @@ export { registerDesignerTypes, designerTypeIds } from './utils/register-types.m
  * 运行时仍然是宿主提供的那一份 ice-render 模块，不会产生第二份内核。
  */
 export * from 'ice-render';
+export { default as WaterVirtualDoc, ITEM_SYMBOL, ITEM_LABEL, ITEM_PIPE } from './virtual/WaterVirtualDoc.mjs';
+export type { WaterVirtualDocOptions } from './virtual/WaterVirtualDoc.mjs';

package/dist/types/index.d.ts

@@ -79,3 +79,5 @@ export { registerDesignerTypes, designerTypeIds } from './utils/register-types';
  * 运行时仍然是宿主提供的那一份 ice-render 模块，不会产生第二份内核。
  */
 export * from 'ice-render';
+export { default as WaterVirtualDoc, ITEM_SYMBOL, ITEM_LABEL, ITEM_PIPE } from './virtual/WaterVirtualDoc';
+export type { WaterVirtualDocOptions } from './virtual/WaterVirtualDoc';

package/dist/types/virtual/WaterVirtualDoc.d.mts

@@ -0,0 +1,164 @@
+/**
+ * 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 type { VirtualChildSource, VirtualChildView } from 'ice-render';
+/** 条目类型 */
+export declare const ITEM_SYMBOL = 0;
+export declare const ITEM_LABEL = 1;
+export declare const ITEM_PIPE = 2;
+/** 文档类型键（序列化时写进容器的 `virtual.type`，反序列化按它找工厂）。 */
+export declare const WATER_VIRTUAL_DOC_TYPE = "ied:water-virtual-doc";
+export interface WaterVirtualDocOptions {
+    /** 符号个数（默认 20000）。标注与管线按它派生。 */
+    symbols?: number;
+    /** 栅格列数（默认按世界长宽比算）。 */
+    cols?: number;
+    worldW?: number;
+    worldH?: number;
+    /** 每个符号都配一条到右邻的管线（默认 true）。 */
+    pipes?: boolean;
+}
+export declare class WaterVirtualDoc implements VirtualChildSource {
+    readonly count: number;
+    /** 文档类型键：反序列化时引擎按它找回工厂（见文件末尾的注册）。 */
+    readonly documentType = "ied:water-virtual-doc";
+    /** 符号个数（下标 0..symbolCount-1 是符号，接着是标注，最后是管线） */
+    readonly symbolCount: number;
+    version: number;
+    /** ---- 列存 ---- */
+    readonly type: Uint8Array;
+    readonly x: Float32Array;
+    readonly y: Float32Array;
+    readonly w: Float32Array;
+    readonly h: Float32Array;
+    /** 符号/标注的 kind 索引（TEXT 条目用不到） */
+    readonly kind: Uint8Array;
+    /** 标注 → 它属于哪个符号（符号自己存 -1） */
+    readonly labelOf: Int32Array;
+    /** 管线两端（指向符号下标）与介质 / 管径 */
+    readonly pipeFrom: Int32Array;
+    readonly pipeTo: Int32Array;
+    readonly pipeMedium: Uint8Array;
+    readonly pipeDn: Uint16Array;
+    /** 已物化（批量层让位）标记：**契约要求**——`materialize` 里必须置位 */
+    readonly done: Uint8Array;
+    readonly worldW: number;
+    readonly worldH: number;
+    /** 位号 / 名称的字符串表（按符号下标算：`P-000123` / `水泵`） */
+    tagOf(i: number): string;
+    nameOf(i: number): string;
+    private readonly ice;
+    private readonly cols;
+    private readonly rows;
+    private readonly cell;
+    private readonly gw;
+    private readonly gh;
+    private head;
+    private nodePrim;
+    private nodeNext;
+    private nodeCount;
+    private readonly sprites;
+    /** 每 kind 的 SVG 片段（第一次导出时惰性生成；复合符号导出的正确形态是 def + use）。 */
+    private readonly svgDefs;
+    private readonly scratch;
+    private labelSyncPad;
+    /** 绑定的虚拟层（`paint` 里做标注的窗口同步要用它）。 */
+    private layer;
+    /** 上一次批量落墨的窗口（页面 / 探针读） */
+    lastView: VirtualChildView | null;
+    /** 是否在 `paint` 里自动做"标注窗口同步"（默认开；关掉可以自己驱动） */
+    syncLabelsOnPaint: boolean;
+    constructor(ice: any, options?: WaterVirtualDocOptions);
+    /** 建/重建空间索引（构造期 + 反序列化贴完编辑之后各一次）。 */
+    rebuildIndex(): void;
+    private __addNode;
+    boxAt(i: number, out: Float64Array): void;
+    /** 窗口遍历：网格候选 + 精确盒相交（标注也在内 —— 窗口同步要用它）。 */
+    forEachInBox(x0: number, y0: number, x1: number, y1: number, visit: (i: number) => void): void;
+    private windowStamp;
+    private readonly windowSeen;
+    /** 退化条目（末行的自连管线、零尺寸）：不进索引、不落墨。 */
+    private __degenerate;
+    hitTest(lx: number, ly: number): number;
+    private __hitPrecise;
+    private __segDist;
+    paint(ctx: any, view: VirtualChildView): boolean;
+    /** 绑定虚拟层：标注的物化 / 回收要用引擎的助手（幂等物化 + 回收）。 */
+    attachLayer(layer: any): void;
+    /**
+     * **窗口内标注的物化 / 回收**（混合策略的应用侧循环）。
+     *
+     * 为什么标注不批量画：符号的位号是**每个实例都不同**的字符串，烤成精灵等于每个符号一张图；
+     * 而物化成真 `ICEText` 之后，引擎的**文本位图缓存**会把"同字号同内容的文字"复用起来
+     * （见引擎的 `ObjectCache`），窗口里几百个标注的实际成本远低于逐帧 `fillText`。
+     */
+    syncLabels(view?: VirtualChildView): void;
+    /**
+     * **文档的唯一写入口**（P2 第 3 条）：undo/redo、属性面板这类程序化写都走它。
+     * 返回 false = 补丁不认识（引擎会原样返回 false，调用方自己决定怎么办）。
+     */
+    applyPatch(index: number, patch: Record<string, any>): boolean;
+    /**
+     * **物化组件被改动后的回流**（P2 第 3 条）：引擎在用户拖完 / 属性面板改完后回调到这里，
+     * 文档立刻跟着变（不必等存盘）。
+     */
+    onChildPatched(index: number, patch: Record<string, any>): void;
+    /** 符号下标 → 它的标注下标（-1 = 这个文档没给标注留位）。 */
+    labelIndexOfSymbol(symbolIndex: number): number;
+    private __strokePipe;
+    /** 每次 paint 真正落墨的条目数（探针用） */
+    drawCalls: number;
+    /**
+     * 造一个真组件（**不挂树** —— 引擎的 `materializeVirtualChild` 负责挂进虚拟层）。
+     *
+     * 契约：必须在这里把 `done[i]` 置位，否则批量层会再画一遍。
+     */
+    materialize(i: number): any;
+    /** 窗口内标注的物化 / 回收（应用侧的"混合策略"循环；引擎只提供两个助手）。 */
+    windowItems(view: VirtualChildView, visit: (i: number) => void): void;
+    /** 管线的世界盒（正交路由：横 → 竖 → 横） */
+    private pipeBox;
+    /** 文档占用的"真数据"字节数（探针 / 反馈报告用） */
+    get bytes(): number;
+    /**
+     * **文档载荷**：只存"参数 + 少量编辑"（不存整份列存）。
+     *
+     * 为什么不是整份列存：列存是**确定性生成**的（参数一样 → 内容一样），所以载荷只需要
+     * `params` + `edits`（被拖过的那几个符号的坐标）。实测一份 6 万条目的文档载荷约几 KB，
+     * 而不是 3MB 的列存 —— 快照文件因此仍然是"可读、可 diff"的。
+     */
+    serializeDocument(): any;
+    /** 编辑过的符号（`[下标, x, y]`）：物化组件被拖动后与列存的差异。 */
+    private readonly edits;
+    /** 物化组件的引用（写回与差异检测用）：下标 → 组件。 */
+    readonly liveComponents: Map<number, any>;
+    /** 把已物化组件的坐标与列存对齐（拖过的写回列存，没动的记进 `edits`）。 */
+    syncEditsFromComponents(): void;
+    private recordEdit;
+    /** 由载荷重建（工厂用）。列存按参数确定性重建，再把 `edits` 贴回去。 */
+    static fromPayload(payload: any, ice: any): WaterVirtualDoc;
+    /** 文档包围盒（导出 / 适应视图用）。 */
+    documentBounds(out: Float64Array): boolean;
+    /**
+     * **全量 SVG 导出**（P2 第 1 条）：把整份文档写进 sink。
+     *
+     * 复合符号的矢量表示用"每 kind 一份 def + 每个实例一条 `<use>`"：def 由引擎的
+     * `exportSvg([模板组件])` 生成（**与画布同源**，不会两套几何），2 万个符号因此只有
+     * 21 份 def + 2 万条 use。标注与管线直接写（它们是纯文本 / 折线）。
+     */
+    paintToSvg(sink: any): boolean;
+    /** 用引擎导出**一个模板组件**的 SVG 片段（去掉 `<svg>` 外壳与 `<defs>`）。 */
+    private __svgFragmentOfKind;
+    /**
+     * 每种 kind 渲染一张离屏位图（**rs=2**，缩放贴图时不至于太糊）。
+     *
+     * 为什么走精灵而不是共享 `Path2D`：IED 的 `WaterSymbol` 是**复合组件**（矩形 + 栅条 / 曝气盘 / 刮泥桥…），
+     * 它的外观不是一条路径 —— 组件的离屏位图才是它的正确"批量表示"。
+     */
+    private __mintSprites;
+}
+export default WaterVirtualDoc;

package/dist/types/virtual/WaterVirtualDoc.d.ts

@@ -0,0 +1,164 @@
+/**
+ * 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 type { VirtualChildSource, VirtualChildView } from 'ice-render';
+/** 条目类型 */
+export declare const ITEM_SYMBOL = 0;
+export declare const ITEM_LABEL = 1;
+export declare const ITEM_PIPE = 2;
+/** 文档类型键（序列化时写进容器的 `virtual.type`，反序列化按它找工厂）。 */
+export declare const WATER_VIRTUAL_DOC_TYPE = "ied:water-virtual-doc";
+export interface WaterVirtualDocOptions {
+    /** 符号个数（默认 20000）。标注与管线按它派生。 */
+    symbols?: number;
+    /** 栅格列数（默认按世界长宽比算）。 */
+    cols?: number;
+    worldW?: number;
+    worldH?: number;
+    /** 每个符号都配一条到右邻的管线（默认 true）。 */
+    pipes?: boolean;
+}
+export declare class WaterVirtualDoc implements VirtualChildSource {
+    readonly count: number;
+    /** 文档类型键：反序列化时引擎按它找回工厂（见文件末尾的注册）。 */
+    readonly documentType = "ied:water-virtual-doc";
+    /** 符号个数（下标 0..symbolCount-1 是符号，接着是标注，最后是管线） */
+    readonly symbolCount: number;
+    version: number;
+    /** ---- 列存 ---- */
+    readonly type: Uint8Array;
+    readonly x: Float32Array;
+    readonly y: Float32Array;
+    readonly w: Float32Array;
+    readonly h: Float32Array;
+    /** 符号/标注的 kind 索引（TEXT 条目用不到） */
+    readonly kind: Uint8Array;
+    /** 标注 → 它属于哪个符号（符号自己存 -1） */
+    readonly labelOf: Int32Array;
+    /** 管线两端（指向符号下标）与介质 / 管径 */
+    readonly pipeFrom: Int32Array;
+    readonly pipeTo: Int32Array;
+    readonly pipeMedium: Uint8Array;
+    readonly pipeDn: Uint16Array;
+    /** 已物化（批量层让位）标记：**契约要求**——`materialize` 里必须置位 */
+    readonly done: Uint8Array;
+    readonly worldW: number;
+    readonly worldH: number;
+    /** 位号 / 名称的字符串表（按符号下标算：`P-000123` / `水泵`） */
+    tagOf(i: number): string;
+    nameOf(i: number): string;
+    private readonly ice;
+    private readonly cols;
+    private readonly rows;
+    private readonly cell;
+    private readonly gw;
+    private readonly gh;
+    private head;
+    private nodePrim;
+    private nodeNext;
+    private nodeCount;
+    private readonly sprites;
+    /** 每 kind 的 SVG 片段（第一次导出时惰性生成；复合符号导出的正确形态是 def + use）。 */
+    private readonly svgDefs;
+    private readonly scratch;
+    private labelSyncPad;
+    /** 绑定的虚拟层（`paint` 里做标注的窗口同步要用它）。 */
+    private layer;
+    /** 上一次批量落墨的窗口（页面 / 探针读） */
+    lastView: VirtualChildView | null;
+    /** 是否在 `paint` 里自动做"标注窗口同步"（默认开；关掉可以自己驱动） */
+    syncLabelsOnPaint: boolean;
+    constructor(ice: any, options?: WaterVirtualDocOptions);
+    /** 建/重建空间索引（构造期 + 反序列化贴完编辑之后各一次）。 */
+    rebuildIndex(): void;
+    private __addNode;
+    boxAt(i: number, out: Float64Array): void;
+    /** 窗口遍历：网格候选 + 精确盒相交（标注也在内 —— 窗口同步要用它）。 */
+    forEachInBox(x0: number, y0: number, x1: number, y1: number, visit: (i: number) => void): void;
+    private windowStamp;
+    private readonly windowSeen;
+    /** 退化条目（末行的自连管线、零尺寸）：不进索引、不落墨。 */
+    private __degenerate;
+    hitTest(lx: number, ly: number): number;
+    private __hitPrecise;
+    private __segDist;
+    paint(ctx: any, view: VirtualChildView): boolean;
+    /** 绑定虚拟层：标注的物化 / 回收要用引擎的助手（幂等物化 + 回收）。 */
+    attachLayer(layer: any): void;
+    /**
+     * **窗口内标注的物化 / 回收**（混合策略的应用侧循环）。
+     *
+     * 为什么标注不批量画：符号的位号是**每个实例都不同**的字符串，烤成精灵等于每个符号一张图；
+     * 而物化成真 `ICEText` 之后，引擎的**文本位图缓存**会把"同字号同内容的文字"复用起来
+     * （见引擎的 `ObjectCache`），窗口里几百个标注的实际成本远低于逐帧 `fillText`。
+     */
+    syncLabels(view?: VirtualChildView): void;
+    /**
+     * **文档的唯一写入口**（P2 第 3 条）：undo/redo、属性面板这类程序化写都走它。
+     * 返回 false = 补丁不认识（引擎会原样返回 false，调用方自己决定怎么办）。
+     */
+    applyPatch(index: number, patch: Record<string, any>): boolean;
+    /**
+     * **物化组件被改动后的回流**（P2 第 3 条）：引擎在用户拖完 / 属性面板改完后回调到这里，
+     * 文档立刻跟着变（不必等存盘）。
+     */
+    onChildPatched(index: number, patch: Record<string, any>): void;
+    /** 符号下标 → 它的标注下标（-1 = 这个文档没给标注留位）。 */
+    labelIndexOfSymbol(symbolIndex: number): number;
+    private __strokePipe;
+    /** 每次 paint 真正落墨的条目数（探针用） */
+    drawCalls: number;
+    /**
+     * 造一个真组件（**不挂树** —— 引擎的 `materializeVirtualChild` 负责挂进虚拟层）。
+     *
+     * 契约：必须在这里把 `done[i]` 置位，否则批量层会再画一遍。
+     */
+    materialize(i: number): any;
+    /** 窗口内标注的物化 / 回收（应用侧的"混合策略"循环；引擎只提供两个助手）。 */
+    windowItems(view: VirtualChildView, visit: (i: number) => void): void;
+    /** 管线的世界盒（正交路由：横 → 竖 → 横） */
+    private pipeBox;
+    /** 文档占用的"真数据"字节数（探针 / 反馈报告用） */
+    get bytes(): number;
+    /**
+     * **文档载荷**：只存"参数 + 少量编辑"（不存整份列存）。
+     *
+     * 为什么不是整份列存：列存是**确定性生成**的（参数一样 → 内容一样），所以载荷只需要
+     * `params` + `edits`（被拖过的那几个符号的坐标）。实测一份 6 万条目的文档载荷约几 KB，
+     * 而不是 3MB 的列存 —— 快照文件因此仍然是"可读、可 diff"的。
+     */
+    serializeDocument(): any;
+    /** 编辑过的符号（`[下标, x, y]`）：物化组件被拖动后与列存的差异。 */
+    private readonly edits;
+    /** 物化组件的引用（写回与差异检测用）：下标 → 组件。 */
+    readonly liveComponents: Map<number, any>;
+    /** 把已物化组件的坐标与列存对齐（拖过的写回列存，没动的记进 `edits`）。 */
+    syncEditsFromComponents(): void;
+    private recordEdit;
+    /** 由载荷重建（工厂用）。列存按参数确定性重建，再把 `edits` 贴回去。 */
+    static fromPayload(payload: any, ice: any): WaterVirtualDoc;
+    /** 文档包围盒（导出 / 适应视图用）。 */
+    documentBounds(out: Float64Array): boolean;
+    /**
+     * **全量 SVG 导出**（P2 第 1 条）：把整份文档写进 sink。
+     *
+     * 复合符号的矢量表示用"每 kind 一份 def + 每个实例一条 `<use>`"：def 由引擎的
+     * `exportSvg([模板组件])` 生成（**与画布同源**，不会两套几何），2 万个符号因此只有
+     * 21 份 def + 2 万条 use。标注与管线直接写（它们是纯文本 / 折线）。
+     */
+    paintToSvg(sink: any): boolean;
+    /** 用引擎导出**一个模板组件**的 SVG 片段（去掉 `<svg>` 外壳与 `<defs>`）。 */
+    private __svgFragmentOfKind;
+    /**
+     * 每种 kind 渲染一张离屏位图（**rs=2**，缩放贴图时不至于太糊）。
+     *
+     * 为什么走精灵而不是共享 `Path2D`：IED 的 `WaterSymbol` 是**复合组件**（矩形 + 栅条 / 曝气盘 / 刮泥桥…），
+     * 它的外观不是一条路径 —— 组件的离屏位图才是它的正确"批量表示"。
+     */
+    private __mintSprites;
+}
+export default WaterVirtualDoc;

package/dist/types/water/WaterProcessDesigner.d.mts

@@ -60,7 +60,15 @@ export declare class WaterPipe extends FlowEdge {
 export default class WaterProcessDesigner extends FlowDesigner {
     constructor(ice: any);
     get nodes(): any[];
+    /**
+     * 选中判据：水务的符号不是 `FlowNode` 的分支（`WaterSymbol extends ICEGroup`），
+     * 所以必须在这里把它（与管线）补进"可点选"的集合 —— 否则点符号选不中，
+     * 属性面板永远显示不出来（2026-09-21 实测确认的既有缺陷，与虚拟化无关）。
+     */
+    protected isSelectableComponent(component: any): boolean;
     get edges(): any[];
+    protected isNodeComponent(component: any): boolean;
+    protected isEdgeComponent(component: any): boolean;
     /** 建一个符号（处理单元 / 设备 / 边界） */
     createSymbol(kind: WaterSymbolKind, props?: any): any;
     /** 建一段管线（要标介质；管径缺了会给 warning） */

package/dist/types/water/WaterProcessDesigner.d.ts

@@ -60,7 +60,15 @@ export declare class WaterPipe extends FlowEdge {
 export default class WaterProcessDesigner extends FlowDesigner {
     constructor(ice: any);
     get nodes(): any[];
+    /**
+     * 选中判据：水务的符号不是 `FlowNode` 的分支（`WaterSymbol extends ICEGroup`），
+     * 所以必须在这里把它（与管线）补进"可点选"的集合 —— 否则点符号选不中，
+     * 属性面板永远显示不出来（2026-09-21 实测确认的既有缺陷，与虚拟化无关）。
+     */
+    protected isSelectableComponent(component: any): boolean;
     get edges(): any[];
+    protected isNodeComponent(component: any): boolean;
+    protected isEdgeComponent(component: any): boolean;
     /** 建一个符号（处理单元 / 设备 / 边界） */
     createSymbol(kind: WaterSymbolKind, props?: any): any;
     /** 建一段管线（要标介质；管径缺了会给 warning） */

package/package.json

@@ -1,7 +1,7 @@
 {
   "author": "大漠穷秋",
   "name": "ice-entity-designer",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "An entity designer based on ice-render.",
   "repository": {
     "type": "git",
@@ -59,7 +59,7 @@
     "types:watch": "npm run types:check -- --watch"
   },
   "peerDependencies": {
-    "ice-render": "^4.0.0",
+    "ice-render": "^4.2.0",
     "react": "^18 || ^19",
     "react-dom": "^18 || ^19"
   },
@@ -101,7 +101,7 @@
     "eslint-plugin-react-hooks": "4.6.0",
     "http-server": "14.1.1",
     "husky": "8.0.3",
-    "ice-render": "^4.0.0",
+    "ice-render": "^4.2.0",
     "jest": "29.7.0",
     "jest-environment-jsdom": "29.7.0",
     "lint-staged": "15.5.2",