ice-render 1.0.4 → 1.0.6

package/dist/types/layout/ICEGridLayout.d.mts

@@ -0,0 +1,33 @@
+/**
+ * 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 ICEGroup from '../graphic/container/ICEGroup.mjs';
+import ICELayoutManager from './ICELayoutManager.mjs';
+/**
+ * @class ICEGridLayout 网格布局
+ *
+ * 对齐 Java Swing 的 GridLayout：把容器分成 cols 列，子组件按「行优先」依次填入网格。
+ * 每行高度取该行最高子组件，行间 gapY 间距，列间 gapX 间距。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class ICEGridLayout extends ICELayoutManager {
+    private cols;
+    private gapX;
+    private gapY;
+    constructor(props?: {
+        cols?: number;
+        gapX?: number;
+        gapY?: number;
+    });
+    /**
+     * @overwrite
+     * 按「行优先」把子组件填入 cols 列网格。
+     */
+    layoutContainer(container: ICEGroup): void;
+}
+export default ICEGridLayout;

package/dist/types/layout/ICEGridLayout.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 ICEGroup from '../graphic/container/ICEGroup';
+import ICELayoutManager from './ICELayoutManager';
+/**
+ * @class ICEGridLayout 网格布局
+ *
+ * 对齐 Java Swing 的 GridLayout：把容器分成 cols 列，子组件按「行优先」依次填入网格。
+ * 每行高度取该行最高子组件，行间 gapY 间距，列间 gapX 间距。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class ICEGridLayout extends ICELayoutManager {
+    private cols;
+    private gapX;
+    private gapY;
+    constructor(props?: {
+        cols?: number;
+        gapX?: number;
+        gapY?: number;
+    });
+    /**
+     * @overwrite
+     * 按「行优先」把子组件填入 cols 列网格。
+     */
+    layoutContainer(container: ICEGroup): void;
+}
+export default ICEGridLayout;

package/dist/types/layout/ICELayeredLayout.d.mts

@@ -0,0 +1,49 @@
+/**
+ * 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 ICEGroup from '../graphic/container/ICEGroup.mjs';
+import ICELayoutManager from './ICELayoutManager.mjs';
+/**
+ * @class ICELayeredLayout 分层图布局（dagre 式）
+ *
+ * 用于「图」场景（节点 + 边，如流程图/ER 图），借鉴 dagre 的分层布局思想：
+ * 1. 拓扑分层（最长路径法）：有向边总是从低层指向高层，源在左、汇在右；
+ * 2. 层内排序（重心法）：迭代调整每层节点顺序，减少边交叉；
+ * 3. 算坐标：层号 → left，层内序号 → top（LR 方向）。
+ *
+ * 与 Swing 的「容器布局」（Flow/Grid/Border）不同，本类面向「图」，作为策略框架里的一个特殊实现。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class ICELayeredLayout extends ICELayoutManager {
+    private gapX;
+    private gapY;
+    constructor(props?: {
+        gapX?: number;
+        gapY?: number;
+    });
+    /**
+     * @overwrite
+     * 读容器里的节点（非连线组件）+ 边（ICEPolyLine 的 links），分层布局后 setState 落位。
+     */
+    layoutContainer(container: ICEGroup): void;
+    /**
+     * 拓扑分层（最长路径法）：rank = 所有前驱的最大 rank + 1；无前驱为 0。
+     * 用 visiting 集合处理有向环。
+     */
+    private assignRanks;
+    /**
+     * 层内排序（重心法）：迭代把每层节点按「下一层邻居的平均 order」排序，减少边交叉。
+     */
+    private assignOrders;
+    /**
+     * 算坐标（LR 方向）：rank 递增 → left 递增；层内按 order 垂直排列。
+     * 节点落位后，把每条边（连线）的端点对齐到源/目标节点的插槽（全局坐标）。
+     */
+    private assignCoords;
+}
+export default ICELayeredLayout;

package/dist/types/layout/ICELayeredLayout.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 ICEGroup from '../graphic/container/ICEGroup';
+import ICELayoutManager from './ICELayoutManager';
+/**
+ * @class ICELayeredLayout 分层图布局（dagre 式）
+ *
+ * 用于「图」场景（节点 + 边，如流程图/ER 图），借鉴 dagre 的分层布局思想：
+ * 1. 拓扑分层（最长路径法）：有向边总是从低层指向高层，源在左、汇在右；
+ * 2. 层内排序（重心法）：迭代调整每层节点顺序，减少边交叉；
+ * 3. 算坐标：层号 → left，层内序号 → top（LR 方向）。
+ *
+ * 与 Swing 的「容器布局」（Flow/Grid/Border）不同，本类面向「图」，作为策略框架里的一个特殊实现。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class ICELayeredLayout extends ICELayoutManager {
+    private gapX;
+    private gapY;
+    constructor(props?: {
+        gapX?: number;
+        gapY?: number;
+    });
+    /**
+     * @overwrite
+     * 读容器里的节点（非连线组件）+ 边（ICEPolyLine 的 links），分层布局后 setState 落位。
+     */
+    layoutContainer(container: ICEGroup): void;
+    /**
+     * 拓扑分层（最长路径法）：rank = 所有前驱的最大 rank + 1；无前驱为 0。
+     * 用 visiting 集合处理有向环。
+     */
+    private assignRanks;
+    /**
+     * 层内排序（重心法）：迭代把每层节点按「下一层邻居的平均 order」排序，减少边交叉。
+     */
+    private assignOrders;
+    /**
+     * 算坐标（LR 方向）：rank 递增 → left 递增；层内按 order 垂直排列。
+     * 节点落位后，把每条边（连线）的端点对齐到源/目标节点的插槽（全局坐标）。
+     */
+    private assignCoords;
+}
+export default ICELayeredLayout;

package/dist/types/layout/ICELayoutManager.d.mts

@@ -0,0 +1,33 @@
+/**
+ * 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 ICEGroup from '../graphic/container/ICEGroup.mjs';
+/**
+ * @class ICELayoutManager 布局管理器（抽象基类）
+ *
+ * 借鉴 Java Swing 的 LayoutManager 设计思想——**策略模式**：
+ * - 组件（ICEComponent）只负责「画自己」，不碰布局；
+ * - 容器（ICEGroup）只负责「持有子组件」，通过 setLayout() 持有布局策略；
+ * - 布局管理器（本类及其子类）只负责「摆位置」。
+ *
+ * 核心只有一个方法 layoutContainer(container)：给定容器，计算并设置所有子组件的位置/尺寸。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare abstract class ICELayoutManager {
+    /**
+     * 布局容器：计算并设置所有子组件的位置/尺寸。
+     * @param container 目标容器（ICEGroup）
+     */
+    abstract layoutContainer(container: ICEGroup): void;
+    /**
+     * 计算容器内内容的「首选尺寸」（可选，默认 [0,0]）。
+     * 子类可按需覆盖。
+     */
+    getPreferredSize(container: ICEGroup): [number, number];
+}
+export default ICELayoutManager;

package/dist/types/layout/ICELayoutManager.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 ICEGroup from '../graphic/container/ICEGroup';
+/**
+ * @class ICELayoutManager 布局管理器（抽象基类）
+ *
+ * 借鉴 Java Swing 的 LayoutManager 设计思想——**策略模式**：
+ * - 组件（ICEComponent）只负责「画自己」，不碰布局；
+ * - 容器（ICEGroup）只负责「持有子组件」，通过 setLayout() 持有布局策略；
+ * - 布局管理器（本类及其子类）只负责「摆位置」。
+ *
+ * 核心只有一个方法 layoutContainer(container)：给定容器，计算并设置所有子组件的位置/尺寸。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare abstract class ICELayoutManager {
+    /**
+     * 布局容器：计算并设置所有子组件的位置/尺寸。
+     * @param container 目标容器（ICEGroup）
+     */
+    abstract layoutContainer(container: ICEGroup): void;
+    /**
+     * 计算容器内内容的「首选尺寸」（可选，默认 [0,0]）。
+     * 子类可按需覆盖。
+     */
+    getPreferredSize(container: ICEGroup): [number, number];
+}
+export default ICELayoutManager;

package/dist/types/layout/ICEOverlayLayout.d.mts

@@ -0,0 +1,25 @@
+/**
+ * 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 ICEGroup from '../graphic/container/ICEGroup.mjs';
+import ICELayoutManager from './ICELayoutManager.mjs';
+/**
+ * @class ICEOverlayLayout 叠加布局
+ *
+ * 对齐 Java Swing 的 OverlayLayout：所有子组件叠放在同一位置（左上角）。
+ * 可用于做图层叠加效果。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class ICEOverlayLayout extends ICELayoutManager {
+    /**
+     * @overwrite
+     * 所有子组件叠放到容器左上角。
+     */
+    layoutContainer(container: ICEGroup): void;
+}
+export default ICEOverlayLayout;

package/dist/types/layout/ICEOverlayLayout.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 ICEGroup from '../graphic/container/ICEGroup';
+import ICELayoutManager from './ICELayoutManager';
+/**
+ * @class ICEOverlayLayout 叠加布局
+ *
+ * 对齐 Java Swing 的 OverlayLayout：所有子组件叠放在同一位置（左上角）。
+ * 可用于做图层叠加效果。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class ICEOverlayLayout extends ICELayoutManager {
+    /**
+     * @overwrite
+     * 所有子组件叠放到容器左上角。
+     */
+    layoutContainer(container: ICEGroup): void;
+}
+export default ICEOverlayLayout;

package/dist/types/persistence/Deserializer.d.mts

@@ -0,0 +1,43 @@
+/**
+ * 序列化格式迁移表：`to` 为目标版本，按升序执行。
+ *
+ * 需要变更数据格式时，把 SERIALIZATION_VERSION 加 1 并在此追加一条迁移：
+ * `SERIALIZATION_MIGRATIONS.push({ to: 2, run: (json) => { ...改写 json 结构... } });`
+ * 当前版本为 1，尚无迁移（仅保留机制与回归用例）。
+ */
+export declare const SERIALIZATION_MIGRATIONS: Array<{
+    to: number;
+    run: (jsonObj: any) => void;
+}>;
+/**
+ * @class Deserializer
+ *
+ * 把 JSON 字符串反解析成图形。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+export default class Deserializer {
+    private ice;
+    constructor(ice: any);
+    /** 本次反序列化中遇到的、未注册的组件类型名（去重）。供应用层提示用户 registerType 后重载。 */
+    private _unknownTypes;
+    get unknownTypes(): string[];
+    fromJSONObject(jsonObj: any): void;
+    fromJSONString(jsonStr: string): void;
+    /**
+     * 版本迁移钩子：当序列化格式版本变化时，在此处按版本逐级升级数据结构。
+     * 当前版本为 {@link SERIALIZATION_VERSION}，低于该版本的旧数据在此迁移。
+     */
+    private migrate;
+    /**
+     * 递归反序列化。
+     *
+     * 容错：遇到未注册的类型时**跳过该节点（含其子树）并记录**，而不是抛错终止整图加载
+     * （旧实现直接 `new undefined(...)` 抛 TypeError，一个未知组件会导致整份数据打不开）。
+     * 注意：生产构建会用 rollup-plugin-strip 去掉 console.*，因此告警也可能消失；
+     * 应用层应以 `deserializer.unknownTypes` 为准做提示。
+     *
+     * @returns 创建出的实例；跳过时返回 null
+     */
+    private decodeRecursively;
+}

package/dist/types/persistence/Deserializer.d.ts

@@ -1,14 +1,43 @@
-/**
- * @class Deserializer
- *
- * 把 JSON 字符串反解析成图形。
- *
- * @author 大漠穷秋<damoqiongqiu@126.com>
- */
-export default class Deserializer {
-    private ice;
-    constructor(ice: any);
-    fromJSONObject(jsonObj: any): void;
-    fromJSONString(jsonStr: string): void;
-    private decodeRecursively;
-}
+/**
+ * 序列化格式迁移表：`to` 为目标版本，按升序执行。
+ *
+ * 需要变更数据格式时，把 SERIALIZATION_VERSION 加 1 并在此追加一条迁移：
+ * `SERIALIZATION_MIGRATIONS.push({ to: 2, run: (json) => { ...改写 json 结构... } });`
+ * 当前版本为 1，尚无迁移（仅保留机制与回归用例）。
+ */
+export declare const SERIALIZATION_MIGRATIONS: Array<{
+    to: number;
+    run: (jsonObj: any) => void;
+}>;
+/**
+ * @class Deserializer
+ *
+ * 把 JSON 字符串反解析成图形。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+export default class Deserializer {
+    private ice;
+    constructor(ice: any);
+    /** 本次反序列化中遇到的、未注册的组件类型名（去重）。供应用层提示用户 registerType 后重载。 */
+    private _unknownTypes;
+    get unknownTypes(): string[];
+    fromJSONObject(jsonObj: any): void;
+    fromJSONString(jsonStr: string): void;
+    /**
+     * 版本迁移钩子：当序列化格式版本变化时，在此处按版本逐级升级数据结构。
+     * 当前版本为 {@link SERIALIZATION_VERSION}，低于该版本的旧数据在此迁移。
+     */
+    private migrate;
+    /**
+     * 递归反序列化。
+     *
+     * 容错：遇到未注册的类型时**跳过该节点（含其子树）并记录**，而不是抛错终止整图加载
+     * （旧实现直接 `new undefined(...)` 抛 TypeError，一个未知组件会导致整份数据打不开）。
+     * 注意：生产构建会用 rollup-plugin-strip 去掉 console.*，因此告警也可能消失；
+     * 应用层应以 `deserializer.unknownTypes` 为准做提示。
+     *
+     * @returns 创建出的实例；跳过时返回 null
+     */
+    private decodeRecursively;
+}

package/dist/types/persistence/Serializer.d.mts

@@ -0,0 +1,35 @@
+/**
+ * 序列化格式版本号。数据结构发生变化时递增，并在 Deserializer 中做对应迁移。
+ */
+export declare const SERIALIZATION_VERSION = 1;
+/**
+ * @class Serializer
+ *
+ * 把图形序列化成 JSON 字符串。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+export default class Serializer {
+    private ice;
+    constructor(ice: any);
+    /**
+     * 把对象序列化成 JSON 字符串：
+     * - 容器型组件需要负责子节点的序列化操作
+     * - 如果组件不需要序列化，需要返回 null
+     * @returns Object
+     */
+    toJSONString(): string;
+    /**
+     * 把对象序列化成 JSON 对象：
+     * - 容器型组件需要负责子节点的序列化操作
+     * - 如果组件不需要序列化，需要返回 null
+     * @returns Object
+     */
+    toJSONObject(): object;
+    private encodeRecursively;
+    /**
+     * 只序列化用户数据，排除运行时缓存/计算值（linearMatrix/composedMatrix/localOrigin/
+     * absoluteOrigin/dots/textHeight 等）。
+     */
+    private pickSerializableState;
+}

package/dist/types/persistence/Serializer.d.ts

@@ -1,26 +1,35 @@
-/**
- * @class Serializer
- *
- * 把图形序列化成 JSON 字符串。
- *
- * @author 大漠穷秋<damoqiongqiu@126.com>
- */
-export default class Serializer {
-    private ice;
-    constructor(ice: any);
-    /**
-     * 把对象序列化成 JSON 字符串：
-     * - 容器型组件需要负责子节点的序列化操作
-     * - 如果组件不需要序列化，需要返回 null
-     * @returns Object
-     */
-    toJSONString(): string;
-    /**
-     * 把对象序列化成 JSON 对象：
-     * - 容器型组件需要负责子节点的序列化操作
-     * - 如果组件不需要序列化，需要返回 null
-     * @returns Object
-     */
-    toJSONObject(): object;
-    private encodeRecursively;
-}
+/**
+ * 序列化格式版本号。数据结构发生变化时递增，并在 Deserializer 中做对应迁移。
+ */
+export declare const SERIALIZATION_VERSION = 1;
+/**
+ * @class Serializer
+ *
+ * 把图形序列化成 JSON 字符串。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+export default class Serializer {
+    private ice;
+    constructor(ice: any);
+    /**
+     * 把对象序列化成 JSON 字符串：
+     * - 容器型组件需要负责子节点的序列化操作
+     * - 如果组件不需要序列化，需要返回 null
+     * @returns Object
+     */
+    toJSONString(): string;
+    /**
+     * 把对象序列化成 JSON 对象：
+     * - 容器型组件需要负责子节点的序列化操作
+     * - 如果组件不需要序列化，需要返回 null
+     * @returns Object
+     */
+    toJSONObject(): object;
+    private encodeRecursively;
+    /**
+     * 只序列化用户数据，排除运行时缓存/计算值（linearMatrix/composedMatrix/localOrigin/
+     * absoluteOrigin/dots/textHeight 等）。
+     */
+    private pickSerializableState;
+}

package/dist/types/plugin/PluginHost.d.mts

@@ -0,0 +1,86 @@
+/**
+ * 插件宿主：为引擎提供「组件 / 渲染 / 交互工具」三层注册点。
+ *
+ * 设计取向与 09-roadmap 的边界一致——**只提供原语，不做应用层 UX**：
+ * - 组件层：插件声明自定义图元类型，宿主代为 `registerType`（因此自动获得
+ *   序列化 typeId 反查能力，见 `ICE.getTypeId`）。
+ * - 渲染层：插件拿到每帧的绘制回调，在与组件相同的坐标系（世界坐标）下叠加绘制。
+ *   局部重绘帧里回调在 clip 之内执行，语义与组件一致（超出脏区域的旧内容不会被擦除也不会被重画；
+ *   若插件内容会随时间变化而没有任何组件变脏，引擎本身会因「无脏组件」回退全量，仍然正确）。
+ * - 交互工具层：插件按 `match(component)` 声明自己的工具组件；宿主复用既有 `toolNodes`
+ *   机制做 add/remove，`exclusive` 为真时禁用内置变换/连线面板。
+ *
+ * 生命周期：`ICE.use(plugin)` 幂等（按 `name` 去重）→ 调用 `setup(ice)`；
+ * `ICE.unuse(name)` → 调用 `teardown(ice)` 并撤销该插件注册的工具与渲染回调。
+ * 类型注册（`components`）在 unuse 后**保留**——反序列化仍可能依赖它，且撤销类型会让已存数据失效。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+export interface ICERenderFrame {
+    ctx: any;
+    /** 当前渲染模式 */
+    mode: 'full' | 'dirty-rect';
+    /** 局部重绘时的脏区域（世界坐标 [minX,minY,maxX,maxY]）；全量帧为 null */
+    region: number[] | null;
+    /** 画布尺寸（设备像素） */
+    width: number;
+    height: number;
+}
+export type ICERenderHook = (frame: ICERenderFrame) => void;
+export interface ICEPluginTool {
+    /** 插件内唯一 id（用于幂等注册与撤销） */
+    id: string;
+    /** 该工具是否应作用于当前选中的组件 */
+    match: (component: any, ice: any) => boolean;
+    /** 创建工具组件（会被加到 ICE.toolNodes，不参与序列化） */
+    create: () => any;
+    /**
+     * 命中时是否屏蔽内置变换/连线面板。
+     * 默认 false（叠加在内置面板之上）；为 true 时内置面板会被禁用，避免与插件工具重叠。
+     */
+    exclusive?: boolean;
+    /** 可选：目标组件变化时回调（同一工具实例被复用，避免每次选中都重建） */
+    onTargetChange?: (tool: any, component: any) => void;
+}
+export interface ICEPlugin {
+    /** 插件唯一名（幂等注册键） */
+    name: string;
+    /** 组件层：typeId → 构造函数 */
+    components?: Record<string, new (...args: any[]) => any>;
+    /** 渲染层：每帧绘制回调（世界坐标） */
+    render?: ICERenderHook;
+    /** 交互工具层 */
+    tools?: ICEPluginTool[];
+    /** 注册时调用（可在此绑定事件、注册主题等） */
+    setup?: (ice: any) => void;
+    /** 注销时调用（应释放自己申请的资源） */
+    teardown?: (ice: any) => void;
+}
+export default class PluginHost {
+    private ice;
+    private plugins;
+    /** 渲染回调，按注册顺序调用 */
+    private renderHooks;
+    private tools;
+    constructor(ice: any);
+    /** 已注册插件名（只读快照） */
+    get names(): string[];
+    has(name: string): boolean;
+    hasRenderHooks(): boolean;
+    /** 幂等注册：同名插件重复 use 直接返回 false（不重复 setup） */
+    use(plugin: ICEPlugin): boolean;
+    /** 注销插件：撤销其渲染回调与工具，并调用 teardown（类型注册保留） */
+    unuse(name: string): boolean;
+    /** 渲染钩子：由 CanvasRenderer 在绘制完组件与工具后调用（世界坐标、clip 之内） */
+    invokeRenderHooks(frame: ICERenderFrame): void;
+    /**
+     * 选中变化时同步插件工具：命中的挂上、失配的摘下。
+     * @returns 是否存在「排他」工具命中（命中时调用方应禁用内置面板）
+     */
+    syncTools(component: any): boolean;
+    /** 全部摘下（如 clearAll 时） */
+    detachAllTools(): void;
+    private detachTool;
+    /** destroy 时清空（不调用 teardown，交由 ICE.destroy 统一处理） */
+    clear(): void;
+}

package/dist/types/plugin/PluginHost.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 插件宿主：为引擎提供「组件 / 渲染 / 交互工具」三层注册点。
+ *
+ * 设计取向与 09-roadmap 的边界一致——**只提供原语，不做应用层 UX**：
+ * - 组件层：插件声明自定义图元类型，宿主代为 `registerType`（因此自动获得
+ *   序列化 typeId 反查能力，见 `ICE.getTypeId`）。
+ * - 渲染层：插件拿到每帧的绘制回调，在与组件相同的坐标系（世界坐标）下叠加绘制。
+ *   局部重绘帧里回调在 clip 之内执行，语义与组件一致（超出脏区域的旧内容不会被擦除也不会被重画；
+ *   若插件内容会随时间变化而没有任何组件变脏，引擎本身会因「无脏组件」回退全量，仍然正确）。
+ * - 交互工具层：插件按 `match(component)` 声明自己的工具组件；宿主复用既有 `toolNodes`
+ *   机制做 add/remove，`exclusive` 为真时禁用内置变换/连线面板。
+ *
+ * 生命周期：`ICE.use(plugin)` 幂等（按 `name` 去重）→ 调用 `setup(ice)`；
+ * `ICE.unuse(name)` → 调用 `teardown(ice)` 并撤销该插件注册的工具与渲染回调。
+ * 类型注册（`components`）在 unuse 后**保留**——反序列化仍可能依赖它，且撤销类型会让已存数据失效。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+export interface ICERenderFrame {
+    ctx: any;
+    /** 当前渲染模式 */
+    mode: 'full' | 'dirty-rect';
+    /** 局部重绘时的脏区域（世界坐标 [minX,minY,maxX,maxY]）；全量帧为 null */
+    region: number[] | null;
+    /** 画布尺寸（设备像素） */
+    width: number;
+    height: number;
+}
+export type ICERenderHook = (frame: ICERenderFrame) => void;
+export interface ICEPluginTool {
+    /** 插件内唯一 id（用于幂等注册与撤销） */
+    id: string;
+    /** 该工具是否应作用于当前选中的组件 */
+    match: (component: any, ice: any) => boolean;
+    /** 创建工具组件（会被加到 ICE.toolNodes，不参与序列化） */
+    create: () => any;
+    /**
+     * 命中时是否屏蔽内置变换/连线面板。
+     * 默认 false（叠加在内置面板之上）；为 true 时内置面板会被禁用，避免与插件工具重叠。
+     */
+    exclusive?: boolean;
+    /** 可选：目标组件变化时回调（同一工具实例被复用，避免每次选中都重建） */
+    onTargetChange?: (tool: any, component: any) => void;
+}
+export interface ICEPlugin {
+    /** 插件唯一名（幂等注册键） */
+    name: string;
+    /** 组件层：typeId → 构造函数 */
+    components?: Record<string, new (...args: any[]) => any>;
+    /** 渲染层：每帧绘制回调（世界坐标） */
+    render?: ICERenderHook;
+    /** 交互工具层 */
+    tools?: ICEPluginTool[];
+    /** 注册时调用（可在此绑定事件、注册主题等） */
+    setup?: (ice: any) => void;
+    /** 注销时调用（应释放自己申请的资源） */
+    teardown?: (ice: any) => void;
+}
+export default class PluginHost {
+    private ice;
+    private plugins;
+    /** 渲染回调，按注册顺序调用 */
+    private renderHooks;
+    private tools;
+    constructor(ice: any);
+    /** 已注册插件名（只读快照） */
+    get names(): string[];
+    has(name: string): boolean;
+    hasRenderHooks(): boolean;
+    /** 幂等注册：同名插件重复 use 直接返回 false（不重复 setup） */
+    use(plugin: ICEPlugin): boolean;
+    /** 注销插件：撤销其渲染回调与工具，并调用 teardown（类型注册保留） */
+    unuse(name: string): boolean;
+    /** 渲染钩子：由 CanvasRenderer 在绘制完组件与工具后调用（世界坐标、clip 之内） */
+    invokeRenderHooks(frame: ICERenderFrame): void;
+    /**
+     * 选中变化时同步插件工具：命中的挂上、失配的摘下。
+     * @returns 是否存在「排他」工具命中（命中时调用方应禁用内置面板）
+     */
+    syncTools(component: any): boolean;
+    /** 全部摘下（如 clearAll 时） */
+    detachAllTools(): void;
+    private detachTool;
+    /** destroy 时清空（不调用 teardown，交由 ICE.destroy 统一处理） */
+    clear(): void;
+}