ice-render 1.0.4 → 1.0.6

package/dist/types/control-panel/transform-controls/TransformControlPanel.d.mts

@@ -0,0 +1,83 @@
+import ICEComponent from '../../graphic/ICEComponent.mjs';
+import ICEControlPanel from '../ICEControlPanel.mjs';
+/**
+ * @class TransformControlPanel
+ *
+ * 变换控制面板
+ *
+ * - TransformControlPanel 本身总是直接画在 canvas 上，不是任何组件的孩子。
+ * - TransformControlPanel 是全局单例，在任意时刻，不可能同时出现多个 TransformControlPanel 的实例，因为在图形化的用户交互模式下，用户无法同时操控多个控制面板。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+export default class TransformControlPanel extends ICEControlPanel {
+    private rotateControlInstance;
+    private rotateControlSize;
+    private rotateControlOffsetY;
+    private resizeControlInstanceCache;
+    private resizeControlSize;
+    constructor(props: any);
+    /**
+     * @method initControls
+     * 添加尺寸和旋转变换手柄，初始化时添加在内部的[0,0]位置，此方法只创建对象实例，不执行渲染操作。
+     * 创建 8 个 ResizeControl
+     * 计算手柄位于父组件的哪一个象限中，有以下取值：
+     *  - 1: 第1象限；
+     *  - 2: 第2象限；
+     *  - 3: 第3象限；
+     *  - 4: 第4象限；
+     *  - 5: 位于X轴上方，y值为负，不属于任何象限；
+     *  - 6: 位于X轴下方，y值为正，不属于任何象限；
+     *  - 7: 位于Y轴左侧，x值为负，不属于任何象限；
+     *  - 8: 位于Y轴右侧，x值为正，不属于任何象限；
+     * 默认创建顺序，从左上角开始顺时针：tl:2/t:5/tr:1/r:8/rb:4/b:6/lb:3/l:7
+     * 第1和第3象限可以交换位置
+     * 第2和第4象限可以交换位置
+     * X 轴正负可以交换位置
+     * Y 轴正负可以交换位置
+     * TODO:添加斜切手柄？
+     */
+    protected initControls(): void;
+    protected initEvents(): void;
+    enable(): void;
+    disable(): void;
+    /**
+     * @overwrite
+     * @method keyboardEvtHandler 键盘事件处理
+     * !ICEControlPanel 的 zIndex 总是大于其它组件，当 ICEControlPanel 显示时，总是会优先判定为被选中的组件，会导致对应的 _targetComponent 收不到鼠标和键盘事件，所以 ICEControlPanel 的实现类需要自己考虑是否需要进行事件转发。
+     * !如果当前的 targetComponent 不为空，转发键盘事件。
+     * @see {ICEControlPanel}
+     * @see {ICEComponent}
+     * @param evt
+     * @returns
+     */
+    protected keyboardEvtHandler(evt: any): void;
+    private rotateEvtHandler;
+    private resizeEvtHandler;
+    /**
+     * @overwrite
+     * @method updateControlPositions 更新内部控制手柄的位置
+     *
+     * 控制面板每次重绘时，会在 doRender() 方法内部会调用 updateControlPositions() 来 更新控制手柄的位置。
+     * @see ICEConrolPanel.doRender()
+     */
+    protected updateControlPositions(): void;
+    protected updatePanel(): void;
+    /**
+     * 目标被移除时的处理。
+     *
+     * 必须是**稳定引用**：旧实现用 `once(BEFORE_REMOVE, () => {...})`，而 `once` 内部会把回调
+     * 再包一层，导致这个箭头函数永远无法被 `off` —— 反复选中组件会在每个组件上累积
+     * 无法回收的监听（内存泄漏 + 幽灵回调）。这里改为具名属性 + `on`，
+     * 由 setter 负责在切换目标时 `off` 掉（`on` 本身对 (fn, scope) 幂等，也不会重复注册）。
+     */
+    private __onTargetRemoved;
+    set targetComponent(component: ICEComponent);
+    get targetComponent(): ICEComponent;
+    /**
+     * 交换两个 Control 的象限
+     * @param control
+     * @param quadrant
+     */
+    toggleControlQuadrant(control: any, oldQuadrant: number, newQuadrant: number): void;
+}

package/dist/types/control-panel/transform-controls/TransformControlPanel.d.ts

@@ -1,74 +1,83 @@
-import ICEComponent from '../../graphic/ICEComponent';
-import ICEControlPanel from '../ICEControlPanel';
-/**
- * @class TransformControlPanel
- *
- * 变换控制面板
- *
- * - TransformControlPanel 本身总是直接画在 canvas 上，不是任何组件的孩子。
- * - TransformControlPanel 是全局单例，在任意时刻，不可能同时出现多个 TransformControlPanel 的实例，因为在图形化的用户交互模式下，用户无法同时操控多个控制面板。
- *
- * @author 大漠穷秋<damoqiongqiu@126.com>
- */
-export default class TransformControlPanel extends ICEControlPanel {
-    private rotateControlInstance;
-    private rotateControlSize;
-    private rotateControlffsetY;
-    private resizeControlInstanceCache;
-    private resizeControlSize;
-    constructor(props: any);
-    /**
-     * @method initControls
-     * 添加尺寸和旋转变换手柄，初始化时添加在内部的[0,0]位置，此方法只创建对象实例，不执行渲染操作。
-     * 创建 8 个 ResizeControl
-     * 计算手柄位于父组件的哪一个象限中，有以下取值：
-     *  - 1: 第1象限；
-     *  - 2: 第2象限；
-     *  - 3: 第3象限；
-     *  - 4: 第4象限；
-     *  - 5: 位于X轴上方，y值为负，不属于任何象限；
-     *  - 6: 位于X轴下方，y值为正，不属于任何象限；
-     *  - 7: 位于Y轴左侧，x值为负，不属于任何象限；
-     *  - 8: 位于Y轴右侧，x值为正，不属于任何象限；
-     * 默认创建顺序，从左上角开始顺时针：tl:2/t:5/tr:1/r:8/rb:4/b:6/lb:3/l:7
-     * 第1和第3象限可以交换位置
-     * 第2和第4象限可以交换位置
-     * X 轴正负可以交换位置
-     * Y 轴正负可以交换位置
-     * TODO:添加斜切手柄？
-     */
-    protected initControls(): void;
-    protected initEvents(): void;
-    enable(): void;
-    disable(): void;
-    /**
-     * @overwrite
-     * @method keyboardEvtHandler 键盘事件处理
-     * !ICEControlPanel 的 zIndex 总是大于其它组件，当 ICEControlPanel 显示时，总是会优先判定为被选中的组件，会导致对应的 _targetComponent 收不到鼠标和键盘事件，所以 ICEControlPanel 的实现类需要自己考虑是否需要进行事件转发。
-     * !如果当前的 targetComponent 不为空，转发键盘事件。
-     * @see {ICEControlPanel}
-     * @see {ICEComponent}
-     * @param evt
-     * @returns
-     */
-    protected keyboardEvtHandler(evt: any): void;
-    private rotateEvtHandler;
-    private resizeEvtHandler;
-    /**
-     * @overwrite
-     * @method updateControlPositions 更新内部控制手柄的位置
-     *
-     * 控制面板每次重绘时，会在 doRender() 方法内部会调用 updateControlPositions() 来 更新控制手柄的位置。
-     * @see ICEConrolPanel.doRender()
-     */
-    protected updateControlPositions(): void;
-    protected updatePanel(): void;
-    set targetComponent(component: ICEComponent);
-    get targetComponent(): ICEComponent;
-    /**
-     * 交换两个 Control 的象限
-     * @param control
-     * @param quadrant
-     */
-    toggleControlQuadrant(control: any, quadrant: number): void;
-}
+import ICEComponent from '../../graphic/ICEComponent';
+import ICEControlPanel from '../ICEControlPanel';
+/**
+ * @class TransformControlPanel
+ *
+ * 变换控制面板
+ *
+ * - TransformControlPanel 本身总是直接画在 canvas 上，不是任何组件的孩子。
+ * - TransformControlPanel 是全局单例，在任意时刻，不可能同时出现多个 TransformControlPanel 的实例，因为在图形化的用户交互模式下，用户无法同时操控多个控制面板。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+export default class TransformControlPanel extends ICEControlPanel {
+    private rotateControlInstance;
+    private rotateControlSize;
+    private rotateControlOffsetY;
+    private resizeControlInstanceCache;
+    private resizeControlSize;
+    constructor(props: any);
+    /**
+     * @method initControls
+     * 添加尺寸和旋转变换手柄，初始化时添加在内部的[0,0]位置，此方法只创建对象实例，不执行渲染操作。
+     * 创建 8 个 ResizeControl
+     * 计算手柄位于父组件的哪一个象限中，有以下取值：
+     *  - 1: 第1象限；
+     *  - 2: 第2象限；
+     *  - 3: 第3象限；
+     *  - 4: 第4象限；
+     *  - 5: 位于X轴上方，y值为负，不属于任何象限；
+     *  - 6: 位于X轴下方，y值为正，不属于任何象限；
+     *  - 7: 位于Y轴左侧，x值为负，不属于任何象限；
+     *  - 8: 位于Y轴右侧，x值为正，不属于任何象限；
+     * 默认创建顺序，从左上角开始顺时针：tl:2/t:5/tr:1/r:8/rb:4/b:6/lb:3/l:7
+     * 第1和第3象限可以交换位置
+     * 第2和第4象限可以交换位置
+     * X 轴正负可以交换位置
+     * Y 轴正负可以交换位置
+     * TODO:添加斜切手柄？
+     */
+    protected initControls(): void;
+    protected initEvents(): void;
+    enable(): void;
+    disable(): void;
+    /**
+     * @overwrite
+     * @method keyboardEvtHandler 键盘事件处理
+     * !ICEControlPanel 的 zIndex 总是大于其它组件，当 ICEControlPanel 显示时，总是会优先判定为被选中的组件，会导致对应的 _targetComponent 收不到鼠标和键盘事件，所以 ICEControlPanel 的实现类需要自己考虑是否需要进行事件转发。
+     * !如果当前的 targetComponent 不为空，转发键盘事件。
+     * @see {ICEControlPanel}
+     * @see {ICEComponent}
+     * @param evt
+     * @returns
+     */
+    protected keyboardEvtHandler(evt: any): void;
+    private rotateEvtHandler;
+    private resizeEvtHandler;
+    /**
+     * @overwrite
+     * @method updateControlPositions 更新内部控制手柄的位置
+     *
+     * 控制面板每次重绘时，会在 doRender() 方法内部会调用 updateControlPositions() 来 更新控制手柄的位置。
+     * @see ICEConrolPanel.doRender()
+     */
+    protected updateControlPositions(): void;
+    protected updatePanel(): void;
+    /**
+     * 目标被移除时的处理。
+     *
+     * 必须是**稳定引用**：旧实现用 `once(BEFORE_REMOVE, () => {...})`，而 `once` 内部会把回调
+     * 再包一层，导致这个箭头函数永远无法被 `off` —— 反复选中组件会在每个组件上累积
+     * 无法回收的监听（内存泄漏 + 幽灵回调）。这里改为具名属性 + `on`，
+     * 由 setter 负责在切换目标时 `off` 掉（`on` 本身对 (fn, scope) 幂等，也不会重复注册）。
+     */
+    private __onTargetRemoved;
+    set targetComponent(component: ICEComponent);
+    get targetComponent(): ICEComponent;
+    /**
+     * 交换两个 Control 的象限
+     * @param control
+     * @param quadrant
+     */
+    toggleControlQuadrant(control: any, oldQuadrant: number, newQuadrant: number): void;
+}

package/dist/types/control-panel/transform-controls/constraints.d.mts

@@ -0,0 +1,24 @@
+/**
+ * 变换手柄的约束算法（纯函数，便于单测）。
+ *
+ * 这些约束由输入层透传的修饰键驱动（`evt.shiftKey` 等）——注意 DOM 事件的修饰键是原型上的
+ * 不可枚举 getter，`ICEEvent` 的 `for...in` 拷贝带不过来，必须由 `input-normalize` 显式透传。
+ */
+/** 旋转吸附的默认步进（度）。 */
+export declare const ROTATE_SNAP_STEP = 15;
+/**
+ * 等比约束：在「目标尺寸」基础上保持 `currentWidth : currentHeight` 不变。
+ *
+ * 取两个方向中**相对变化更大**的那个作为基准，另一个方向按比例跟随 —— 这样拖动角手柄时
+ * 跟随手感更贴近手指，也不会出现「一个方向已到目标、另一个方向还没动」的粘滞感。
+ * 尺寸取绝对值（翻转由调用方决定，不在这里处理）。
+ */
+export declare function applyAspectLock(currentWidth: number, currentHeight: number, nextWidth: number, nextHeight: number): {
+    width: number;
+    height: number;
+};
+/**
+ * 角度吸附：把角度吸附到 `step` 的整数倍（默认 15°）。
+ * 吸附在**最终角度**上做（调用方已把补偿角加上），避免补偿把吸附结果带偏。
+ */
+export declare function snapAngle(angle: number, step?: number): number;

package/dist/types/control-panel/transform-controls/constraints.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 变换手柄的约束算法（纯函数，便于单测）。
+ *
+ * 这些约束由输入层透传的修饰键驱动（`evt.shiftKey` 等）——注意 DOM 事件的修饰键是原型上的
+ * 不可枚举 getter，`ICEEvent` 的 `for...in` 拷贝带不过来，必须由 `input-normalize` 显式透传。
+ */
+/** 旋转吸附的默认步进（度）。 */
+export declare const ROTATE_SNAP_STEP = 15;
+/**
+ * 等比约束：在「目标尺寸」基础上保持 `currentWidth : currentHeight` 不变。
+ *
+ * 取两个方向中**相对变化更大**的那个作为基准，另一个方向按比例跟随 —— 这样拖动角手柄时
+ * 跟随手感更贴近手指，也不会出现「一个方向已到目标、另一个方向还没动」的粘滞感。
+ * 尺寸取绝对值（翻转由调用方决定，不在这里处理）。
+ */
+export declare function applyAspectLock(currentWidth: number, currentHeight: number, nextWidth: number, nextHeight: number): {
+    width: number;
+    height: number;
+};
+/**
+ * 角度吸附：把角度吸附到 `step` 的整数倍（默认 15°）。
+ * 吸附在**最终角度**上做（调用方已把补偿角加上），避免补偿把吸附结果带偏。
+ */
+export declare function snapAngle(angle: number, step?: number): number;

package/dist/types/cross-platform/PolyfillPath2D.d.mts

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ *
+ */
+/**
+ * @class PolyfillPath2D
+ *
+ * Path2D 的极简 polyfill：无全局 Path2D 构造函数的运行时（如小程序低版本基础库、
+ * Node 环境）中，用它记录路径命令，渲染时再重放到 ctx 当前路径。
+ *
+ * 仅实现引擎用到的 moveTo/lineTo/rect/ellipse/closePath，其余标准 Path2D 方法未实现。
+ */
+export default class PolyfillPath2D {
+    /** 标记这是 polyfill，用于 ICEPath.doRender 区分原生 Path2D 与命令重放 */
+    _isPolyfill: boolean;
+    /** 记录的命令序列，如 [['rect', 0, 0, 10, 10], ['moveTo', 1, 1], ...] */
+    _commands: Array<Array<any>>;
+    /** closePath 是幂等标记（doRender 每帧调用），不重复入队 */
+    _closed: boolean;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
+    quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
+    arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void;
+    rect(x: number, y: number, width: number, height: number): void;
+    ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number, startAngle: number, endAngle: number, counterclockwise: boolean): void;
+    closePath(): void;
+}

package/dist/types/cross-platform/PolyfillPath2D.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ *
+ */
+/**
+ * @class PolyfillPath2D
+ *
+ * Path2D 的极简 polyfill：无全局 Path2D 构造函数的运行时（如小程序低版本基础库、
+ * Node 环境）中，用它记录路径命令，渲染时再重放到 ctx 当前路径。
+ *
+ * 仅实现引擎用到的 moveTo/lineTo/rect/ellipse/closePath，其余标准 Path2D 方法未实现。
+ */
+export default class PolyfillPath2D {
+    /** 标记这是 polyfill，用于 ICEPath.doRender 区分原生 Path2D 与命令重放 */
+    _isPolyfill: boolean;
+    /** 记录的命令序列，如 [['rect', 0, 0, 10, 10], ['moveTo', 1, 1], ...] */
+    _commands: Array<Array<any>>;
+    /** closePath 是幂等标记（doRender 每帧调用），不重复入队 */
+    _closed: boolean;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
+    quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
+    arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void;
+    rect(x: number, y: number, width: number, height: number): void;
+    ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number, startAngle: number, endAngle: number, counterclockwise: boolean): void;
+    closePath(): void;
+}

package/dist/types/cross-platform/root.d.mts

@@ -0,0 +1,7 @@
+/**
+ * 兼容性封装
+ * ! TODO: import https://www.npmjs.com/package/canvas for nodejs platform.
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare let root: any;
+export default root;

package/dist/types/cross-platform/root.d.ts

@@ -1,2 +1,7 @@
-export default root;
-declare let root: any;
+/**
+ * 兼容性封装
+ * ! TODO: import https://www.npmjs.com/package/canvas for nodejs platform.
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare let root: any;
+export default root;

package/dist/types/event/DOMEventDispatcher.d.mts

@@ -0,0 +1,68 @@
+import ICE from '../ICE.mjs';
+/**
+ * @class DOMEventDispatcher
+ *
+ * - DOM 事件派发器，监听事件总线上的输入事件，派发给 canvas 内指定的组件。
+ * - 鼠标 / 指针 / 触摸 / 滚轮 / 键盘事件都通过此工具类派发。
+ *
+ * 输入归一化（本类的关键职责）：
+ * - 底层无论 pointer / mouse / touch，都在这里统一成 canvas 内坐标
+ *   （`clientX - canvasRect.left`）与屏幕位移 movement，然后写回事件对象。
+ *   这样组件、拖拽、变换手柄、对齐吸附、命中检测都无需区分输入源。
+ * - pointer / touch 会额外以「鼠标语义名」（mousedown/mousemove/mouseup）再派发一次，
+ *   保证既有 `on('mousedown', ...)` 代码零改动即可在触摸设备上工作。
+ * - 命中检测用的 canvas 矩形在非移动类事件上刷新，页面滚动 / 布局变化后仍正确。
+ *
+ * @see {DOMEventInterceptor}
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class DOMEventDispatcher {
+    private selectionCandidates;
+    private ice;
+    private _stopped;
+    /** 上一次归一化输入，用于在原生 movement 缺失（触摸）时补算位移。 */
+    private __lastInput;
+    /**
+     * 键盘事件的焦点组件（无障碍 / 键盘导航）。
+     * 由应用层通过 `ICE.setFocusedComponent()` 设置；为 null 时维持既有行为
+     * ——键盘事件派发给「上次点击命中的组件」。
+     */
+    focusedComponent: any;
+    constructor(ice: ICE);
+    start(): this;
+    /**
+     * 指针捕获：`pointerdown` 时把指针捕获到画布，`pointerup` / `pointercancel` 时释放。
+     *
+     * 为什么需要：拖组件、拖变换手柄、拖连线钩子时，指针很容易移出画布范围。没有捕获就会出现
+     * 「拖着拖着不跟手」甚至「松开鼠标了还在拖」—— 因为后续 `pointermove` / `pointerup`
+     * 被派发到了画布之外的元素上。捕获后这些事件会被重定向回画布。
+     *
+     * 只处理 Pointer Events 通道：mouse/touch 旧通道的 move/up 会冒泡到 window，本来就不会丢。
+     */
+    private __handlePointerCapture;
+    /**
+     * 把事件派发给命中的组件与事件总线。
+     * 组件先收到，总线后收到（与既有语义一致：总线始终会收到一次）。
+     */
+    private __dispatch;
+    /**
+     * 取 canvas 矩形用于坐标换算。
+     * 移动类事件频率高（每帧可能多次），复用缓存；其余事件刷新一次，
+     * 保证页面滚动 / 布局变化后命中检测不错位。
+     */
+    private __resolveCanvasRect;
+    set stopped(flag: boolean);
+    get stopped(): boolean;
+    /**
+     * @method findTargetComponent
+     *
+     * 找到被点击的对象，用代码触发 click 事件。
+     * 在点击状态下，每次只能点击一个对象，当前不支持 DOM 冒泡特性。
+     *
+     * 坐标约定：`evt.offsetX/offsetY` 已由输入归一化保证是「canvas 内坐标」。
+     *
+     * @returns
+     */
+    private findTargetComponent;
+}
+export default DOMEventDispatcher;

package/dist/types/event/DOMEventDispatcher.d.ts

@@ -1,29 +1,68 @@
-import ICE from '../ICE';
-/**
- * @class DOMEventDispatcher
- *
- * - DOM 事件转发器，监听事件总线上的事件，转发给 canvas 内部指定的组件。
- * - 原生的鼠标和键盘事件都通过此工具类进行转发。
- *
- * @see {DOMEventInterceptor}
- * @author 大漠穷秋<damoqiongqiu@126.com>
- */
-declare class DOMEventDispatcher {
-    private selectionCandidates;
-    private ice;
-    private _stopped;
-    constructor(ice: ICE);
-    start(): this;
-    set stopped(flag: boolean);
-    get stopped(): boolean;
-    /**
-     * @method findTargetComponent
-     *
-     * 找到被点击的对象，用代码触发 click 事件。
-     * 在点击状态下，每次只能点击一个对象，当前不支持 DOM 冒泡特性。
-     *
-     * @returns
-     */
-    private findTargetComponent;
-}
-export default DOMEventDispatcher;
+import ICE from '../ICE';
+/**
+ * @class DOMEventDispatcher
+ *
+ * - DOM 事件派发器，监听事件总线上的输入事件，派发给 canvas 内指定的组件。
+ * - 鼠标 / 指针 / 触摸 / 滚轮 / 键盘事件都通过此工具类派发。
+ *
+ * 输入归一化（本类的关键职责）：
+ * - 底层无论 pointer / mouse / touch，都在这里统一成 canvas 内坐标
+ *   （`clientX - canvasRect.left`）与屏幕位移 movement，然后写回事件对象。
+ *   这样组件、拖拽、变换手柄、对齐吸附、命中检测都无需区分输入源。
+ * - pointer / touch 会额外以「鼠标语义名」（mousedown/mousemove/mouseup）再派发一次，
+ *   保证既有 `on('mousedown', ...)` 代码零改动即可在触摸设备上工作。
+ * - 命中检测用的 canvas 矩形在非移动类事件上刷新，页面滚动 / 布局变化后仍正确。
+ *
+ * @see {DOMEventInterceptor}
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class DOMEventDispatcher {
+    private selectionCandidates;
+    private ice;
+    private _stopped;
+    /** 上一次归一化输入，用于在原生 movement 缺失（触摸）时补算位移。 */
+    private __lastInput;
+    /**
+     * 键盘事件的焦点组件（无障碍 / 键盘导航）。
+     * 由应用层通过 `ICE.setFocusedComponent()` 设置；为 null 时维持既有行为
+     * ——键盘事件派发给「上次点击命中的组件」。
+     */
+    focusedComponent: any;
+    constructor(ice: ICE);
+    start(): this;
+    /**
+     * 指针捕获：`pointerdown` 时把指针捕获到画布，`pointerup` / `pointercancel` 时释放。
+     *
+     * 为什么需要：拖组件、拖变换手柄、拖连线钩子时，指针很容易移出画布范围。没有捕获就会出现
+     * 「拖着拖着不跟手」甚至「松开鼠标了还在拖」—— 因为后续 `pointermove` / `pointerup`
+     * 被派发到了画布之外的元素上。捕获后这些事件会被重定向回画布。
+     *
+     * 只处理 Pointer Events 通道：mouse/touch 旧通道的 move/up 会冒泡到 window，本来就不会丢。
+     */
+    private __handlePointerCapture;
+    /**
+     * 把事件派发给命中的组件与事件总线。
+     * 组件先收到，总线后收到（与既有语义一致：总线始终会收到一次）。
+     */
+    private __dispatch;
+    /**
+     * 取 canvas 矩形用于坐标换算。
+     * 移动类事件频率高（每帧可能多次），复用缓存；其余事件刷新一次，
+     * 保证页面滚动 / 布局变化后命中检测不错位。
+     */
+    private __resolveCanvasRect;
+    set stopped(flag: boolean);
+    get stopped(): boolean;
+    /**
+     * @method findTargetComponent
+     *
+     * 找到被点击的对象，用代码触发 click 事件。
+     * 在点击状态下，每次只能点击一个对象，当前不支持 DOM 冒泡特性。
+     *
+     * 坐标约定：`evt.offsetX/offsetY` 已由输入归一化保证是「canvas 内坐标」。
+     *
+     * @returns
+     */
+    private findTargetComponent;
+}
+export default DOMEventDispatcher;

package/dist/types/event/DOMEventInterceptor.d.mts

@@ -0,0 +1,36 @@
+/**
+ * @class DOMEventInterceptor DOM 事件拦截器
+ *
+ * 拦截所有原生的输入事件（指针 / 鼠标 / 触摸 / 滚轮 / 键盘），转发到全局事件总线，
+ * ICE 内部的事件派发器再监听总线，把事件派发给 canvas 内特定的组件。
+ *
+ * - 输入通道按运行时能力选择：有 PointerEvent 则只监听 pointer*（统一鼠标/触控笔/触摸），
+ *   否则回退 mouse* + touch*；见 `buildDomEventList()`。
+ * - 全局只绑定一套 DOM 监听：事件到来时遍历当前所有事件总线转发。
+ *   这样重复 init / 多实例 / React StrictMode 双挂载都不会叠加监听，且 stop() 可以真正解绑。
+ * - wheel 以 passive:false 绑定，便于应用层阻止页面滚动；触摸的滚动抑制由 canvas 上的
+ *   `touch-action: none` 声明式完成（见 ICE.init）。
+ *
+ * @see {DOMEventDispatcher}
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare const DOMEventInterceptor: {
+    evtBuses: any[];
+    __handlers: null | Array<{
+        name: string;
+        handler: (evt: any) => void;
+    }>;
+    /** 当前运行时是否走 PointerEvent 通道（start 时探测并缓存，便于测试断言）。 */
+    __hasPointerEvent: boolean;
+    /**
+     * @method start 绑定全局 DOM 监听（幂等：重复调用不会重复绑定）
+     */
+    start: () => void;
+    /**
+     * @method stop 解绑全局 DOM 监听
+     */
+    stop: () => void;
+    registerEvtBus: (evtBus: any) => void;
+    delEvtBus: (evtBus: any) => void;
+};
+export default DOMEventInterceptor;

package/dist/types/event/DOMEventInterceptor.d.ts

@@ -1,7 +1,36 @@
-export default DOMEventInterceptor;
-declare namespace DOMEventInterceptor {
-    const evtBuses: any[];
-    function start(): void;
-    function regitserEvtBus(evtBus: any): void;
-    function delEvtBus(evtBus: any): void;
-}
+/**
+ * @class DOMEventInterceptor DOM 事件拦截器
+ *
+ * 拦截所有原生的输入事件（指针 / 鼠标 / 触摸 / 滚轮 / 键盘），转发到全局事件总线，
+ * ICE 内部的事件派发器再监听总线，把事件派发给 canvas 内特定的组件。
+ *
+ * - 输入通道按运行时能力选择：有 PointerEvent 则只监听 pointer*（统一鼠标/触控笔/触摸），
+ *   否则回退 mouse* + touch*；见 `buildDomEventList()`。
+ * - 全局只绑定一套 DOM 监听：事件到来时遍历当前所有事件总线转发。
+ *   这样重复 init / 多实例 / React StrictMode 双挂载都不会叠加监听，且 stop() 可以真正解绑。
+ * - wheel 以 passive:false 绑定，便于应用层阻止页面滚动；触摸的滚动抑制由 canvas 上的
+ *   `touch-action: none` 声明式完成（见 ICE.init）。
+ *
+ * @see {DOMEventDispatcher}
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare const DOMEventInterceptor: {
+    evtBuses: any[];
+    __handlers: null | Array<{
+        name: string;
+        handler: (evt: any) => void;
+    }>;
+    /** 当前运行时是否走 PointerEvent 通道（start 时探测并缓存，便于测试断言）。 */
+    __hasPointerEvent: boolean;
+    /**
+     * @method start 绑定全局 DOM 监听（幂等：重复调用不会重复绑定）
+     */
+    start: () => void;
+    /**
+     * @method stop 解绑全局 DOM 监听
+     */
+    stop: () => void;
+    registerEvtBus: (evtBus: any) => void;
+    delEvtBus: (evtBus: any) => void;
+};
+export default DOMEventInterceptor;

package/dist/types/event/EventBus.d.mts

@@ -0,0 +1,27 @@
+/**
+ * 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 ICEEventTarget from './ICEEventTarget.mjs';
+/**
+ * @class EventBus
+ * @singleton
+ *
+ * EventBus 事件总线。
+ *
+ * - canvas 标签内部没有事件机制，ICE 借助于 EventBus 把原生 DOM 事件转发到 canvas 内部(mouse/keyboard/touch)，在转发过程中可能会把原生 DOM 事件转换成 ICEEvent 。
+ * - EventBus 是 ICEEventTarget 的实现类。
+ * - EventBus 是全局单例，同一个 ICE 实例上只能有一个事件总线的实例。
+ * - ICE 内部几乎所有机制都依赖事件总线来实现。
+ * - requestAnimationFrame 会利用事件总线触发 FRAME 事件。
+ *
+ * @see ICEEventTaregt
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class EventBus extends ICEEventTarget {
+    constructor(props?: any);
+}
+export default EventBus;