ice-render 1.0.4 → 1.0.6

package/dist/types/ICE.d.ts

@@ -1,107 +1,369 @@
-import AnimationManager from './animation/AnimationManager';
-import ICEControlPanelManager from './control-panel/ICEControlPanelManager';
-import DOMEventDispatcher from './event/DOMEventDispatcher';
-import EventBus from './event/EventBus';
-import ICEComponent from './graphic/ICEComponent';
-import ICELinkSlotManager from './graphic/link/ICELinkSlotManager';
-import Deserializer from './persistence/Deserializer';
-import Serializer from './persistence/Serializer';
-import ImageCache from './util/ImageCache';
-/**
- * @class ICE
- *
- * - ICE 是整个引擎的主入口类。
- * - 同一个 canvas 标签上只能初始化一个 ICE 实例。
- * - 同一个页面上可以存在多幅图。
- *
- * @author 大漠穷秋<damoqiongqiu@126.com>
- */
-declare class ICE {
-    childNodes: any[];
-    toolNodes: any[];
-    evtBus: EventBus;
-    root: any;
-    canvasEl: any;
-    ctx: any;
-    canvasWidth: number;
-    canvasHeight: number;
-    canvasBoundingClientRect: any;
-    selectionList: Array<any>;
-    typeMapping: {};
-    renderer: any;
-    animationManager: AnimationManager;
-    eventDispatcher: DOMEventDispatcher;
-    controlPanelManager: ICEControlPanelManager;
-    linkSlotManager: ICELinkSlotManager;
-    serializer: Serializer;
-    deserializer: Deserializer;
-    imageCache: ImageCache;
-    private __dirty;
-    constructor();
-    /**
-     * @param ctx DOM id or CanvasContext
-     */
-    init(ctx: any): this;
-    /**
-     * @method addChild
-     * 添加交互工具组件。
-     * 工具组件不触发事件，不产生动画效果。
-     * @param {ICEComponent} tool
-     */
-    addTool(tool: ICEComponent): void;
-    /**
-     * @methos removeTool
-     * 删除交互工具组件。
-     * 工具组件不触发事件，不产生动画效果。
-     * @param tool
-     */
-    removeTool(tool: ICEComponent): void;
-    /**
-     *
-     * 调用 ICE.addChild() 方法，会直接把对象画在 canvas 上。
-     * 如果需要在容器中画组件，参见 @see ICEGroup.addChild() 方法
-     *
-     * @param component
-     */
-    addChild(component: any, markDirty?: boolean): void;
-    addChildren(arr: Array<ICEComponent>): void;
-    removeChild(component: ICEComponent, markDirty?: boolean): void;
-    removeChildren(arr: Array<ICEComponent>): void;
-    clearAll(): void;
-    findComponent(id: string): any;
-    set dirty(flag: boolean);
-    get dirty(): boolean;
-    /**
-     * @method registerType 注册组件类型
-     *
-     * - 需要在反序列化之前调用，否则无法反序列化。
-     * - ICE 内置的类型已经自动注册，不需要手动注册。
-     *
-     * @param className
-     * @param Clazz
-     */
-    registerType(className: string, Clazz: Function): void;
-    /**
-     * @method getType 获取组件构造函数
-     * @param className
-     * @returns
-     */
-    getType(className: string): any;
-    /**
-     * 把对象序列化成 JSON 字符串：
-     * - 容器型组件需要负责子节点的序列化操作
-     * - 如果组件不需要序列化，需要返回 null
-     * @returns Object
-     */
-    toJSONString(): string;
-    /**
-     * 把对象序列化成 JSON 对象：
-     * - 容器型组件需要负责子节点的序列化操作
-     * - 如果组件不需要序列化，需要返回 null
-     * @returns Object
-     */
-    toJSONObject(): object;
-    fromJSONObject(jsonObject: any): void;
-    fromJSONString(jsonStr: string): void;
-}
-export default ICE;
+import AnimationManager from './animation/AnimationManager';
+import ICEControlPanelManager from './control-panel/ICEControlPanelManager';
+import AlignmentGuideManager from './control-panel/AlignmentGuideManager';
+import DOMEventDispatcher from './event/DOMEventDispatcher';
+import EventBus from './event/EventBus';
+import ICEComponent from './graphic/ICEComponent';
+import ICELinkSlotManager from './graphic/link/ICELinkSlotManager';
+import Deserializer from './persistence/Deserializer';
+import Serializer from './persistence/Serializer';
+import PluginHost, { ICEPlugin } from './plugin/PluginHost';
+import { ICEAccessibleNode, ICEAccessibilityOptions } from './a11y/accessibility';
+import ImageCache from './util/ImageCache';
+import { ICETheme, ICESemanticTheme } from './theme/ICETheme';
+/**
+ * @class ICE
+ *
+ * - ICE 是整个引擎的主入口类。
+ * - 同一个 canvas 标签上只能初始化一个 ICE 实例。
+ * - 同一个页面上可以存在多幅图。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class ICE {
+    childNodes: any[];
+    toolNodes: any[];
+    private __childSet;
+    private __toolSet;
+    evtBus: EventBus;
+    root: any;
+    canvasEl: any;
+    ctx: any;
+    canvasWidth: number;
+    canvasHeight: number;
+    canvasBoundingClientRect: any;
+    /** 视口变换（视图缩放/平移）：屏幕 = 世界 * scale + translate。默认单位视口，不影响既有行为。 */
+    viewport: {
+        scale: number;
+        tx: number;
+        ty: number;
+    };
+    /**
+     * 设备像素比。默认 1（不改变既有行为）。
+     *
+     * 传 >1 时（`ICE.init(el, { dpr: 2 })`）：引擎把 canvas 的 backing store 放大到 cssSize*dpr，
+     * 渲染变换乘以 dpr，从而在高分屏上不发虚。**交互侧（命中/拖拽/吸附）仍用 CSS 像素语义**，
+     * 因为鼠标/触摸坐标本身就是 CSS 像素，所以 screenToWorld 不参与 dpr。
+     */
+    dpr: number;
+    /** 渲染用视口缓存（= dpr · viewport），避免每组件每帧分配对象。 */
+    private __renderVp;
+    /**
+     * canvas 内容盒（绘制区）相对视口的偏移与尺寸。
+     *
+     * `getBoundingClientRect()` 返回的是 **border-box**，而 canvas 的绘制区是**内容盒**：
+     * 画布带 border / padding 时，若直接用 rect.left/top 换算鼠标坐标会整体偏移（差一个边框宽），
+     * backing store 尺寸也会被边框撑大。这里在刷新 rect 时一并读取 computedStyle 补偿。
+     */
+    private __contentBox;
+    selectionList: Array<any>;
+    /** 插件宿主：组件 / 渲染 / 交互工具三层注册点，见 `src/plugin/PluginHost.ts`。 */
+    plugins: PluginHost;
+    /**
+     * 当前实例持有的主题（**实例级**，互不污染）。
+     *
+     * 初始值取模块级默认主题；`setTheme()` 只改本实例。
+     * 组件构造时若用了 `preset`，会在加入本实例时按这里的主题重新解析一次
+     * （见 `addChild` / `addTool` 中的 `__reapplyPreset`）。
+     */
+    theme: ICETheme;
+    typeMapping: {};
+    /** 构造函数 → 类型名 的反查表（序列化用）。惰性构建，registerType/init 后失效重建。 */
+    private __typeIdMapping;
+    renderer: any;
+    animationManager: AnimationManager;
+    eventDispatcher: DOMEventDispatcher;
+    controlPanelManager: ICEControlPanelManager;
+    alignmentGuide: AlignmentGuideManager;
+    linkSlotManager: ICELinkSlotManager;
+    serializer: Serializer;
+    deserializer: Deserializer;
+    imageCache: ImageCache;
+    private __dirty;
+    constructor();
+    /** 是否已经完成初始化（用于 init 幂等 / destroy 配对） */
+    private __initialized;
+    /**
+     * 从 init 入参解析出 canvas 元素。
+     * 支持：HTMLCanvasElement、CanvasRenderingContext2D；解析不出则返回 null。
+     */
+    private __resolveCanvasEl;
+    /**
+     * @param ctx DOM id、HTMLCanvasElement 或 CanvasRenderingContext2D
+     * @param options 渲染配置。renderMode: 'dirty-rect'(默认) | 'full'
+     *
+     * 幂等：同一个 ICE 实例重复 init 到同一个 canvas 时直接返回自身。
+     * React StrictMode 下 effect 会被执行两次，幂等可以避免重复挂载 Manager / 重复绑定全局事件。
+     * 若要换一个 canvas，请先调用 destroy()。
+     */
+    init(ctx: any, options?: {
+        renderMode?: 'full' | 'dirty-rect';
+        dpr?: number;
+    }): this;
+    /**
+     * @method destroy 销毁当前实例
+     *
+     * 与 init() 配对：停止所有 Manager、解绑 canvas 上的原生事件、注销全局事件总线（FrameManager / DOMEventInterceptor 都是全局单例，必须显式注销）。
+     * 销毁之后可以再次 init（例如 React 组件重新挂载），不会累积监听或帧循环。
+     */
+    destroy(): void;
+    /**
+     * @method addChild
+     * 添加交互工具组件。
+     * 工具组件不触发事件，不产生动画效果。
+     * @param {ICEComponent} tool
+     */
+    addTool(tool: ICEComponent): void;
+    /**
+     * @methos removeTool
+     * 删除交互工具组件。
+     * 工具组件不触发事件，不产生动画效果。
+     * @param tool
+     */
+    removeTool(tool: ICEComponent): void;
+    /**
+     *
+     * 调用 ICE.addChild() 方法，会直接把对象画在 canvas 上。
+     * 如果需要在容器中画组件，参见 @see ICEGroup.addChild() 方法
+     *
+     * @param component
+     */
+    addChild(component: any, markDirty?: boolean): void;
+    addChildren(arr: Array<ICEComponent>): void;
+    removeChild(component: ICEComponent, markDirty?: boolean): void;
+    removeChildren(arr: Array<ICEComponent>): void;
+    clearAll(): void;
+    /**
+     * 按 id 查找组件。
+     *
+     * 查找范围：**先查顶层 `childNodes`**（同 id 时顶层优先，保持既有优先级），再深度优先递归整棵
+     * 子树。「连线连接嵌套子组件」依赖本方法（`ICEPolyLine.syncConnections` → 本方法）。
+     *
+     * **工具层 `toolNodes` 不参与查找**：工具是 UI 覆盖层（变换/连线手柄等），不应成为连线端点。
+     *
+     * 历史：早期只搜第一层，嵌套场景连线会静默失效；中途曾尝试放开递归但被回退 ——
+     * 当时表现为 `dirty-rect-pixel` 富场景 step1 约 900 px 差异，看起来像「连线端点推导与局部重绘
+     * 冲突」，实际根因是**折线的包围盒是退化的**（`state.width ≈ 0`），导致 dirty-rect 按快照盒
+     * 挑选重画对象时漏掉折线（擦除区域内的折线笔迹丢失）。该根因已修（见 `ICEComponent.__localBox`
+     * 与 `ICEPolyLine.calcComponentParams`），因此递归可以放开。
+     */
+    findComponent(id: string): any;
+    /** 深度优先查找子树（不含工具层）。 */
+    private __findComponentInTree;
+    set dirty(flag: boolean);
+    get dirty(): boolean;
+    /**
+     * @method registerType 注册组件类型
+     *
+     * - 需要在反序列化之前调用，否则无法反序列化。
+     * - ICE 内置的类型已经自动注册，不需要手动注册。
+     *
+     * @param className
+     * @param Clazz
+     */
+    registerType(className: string, Clazz: new (...args: any[]) => any): void;
+    /**
+     * 由构造函数反查稳定的类型名（序列化用）。
+     *
+     * - 已注册的类型：返回注册名（与类的 JS 名解耦，压缩改名不影响已存数据）
+     * - 未注册：返回 undefined，调用方回退到 `constructor.name`（保持既有行为）
+     * - 同一个构造函数注册了多个名字时，**先注册的优先**（内置类型因此不会被别名顶掉）
+     */
+    getTypeId(Clazz: new (...args: any[]) => any): string | undefined;
+    /**
+     * 注册插件（幂等：同名插件重复调用直接返回，不重复 setup）。
+     *
+     * 插件可提供三层扩展点：`components`（自定义图元类型）、`render`（每帧绘制回调）、
+     * `tools`（按选中组件匹配的交互工具）。详见 `src/plugin/PluginHost.ts`。
+     *
+     * @returns 是否本次真的注册（同名已存在时为 false）
+     */
+    use(plugin: ICEPlugin): boolean;
+    /**
+     * 注销插件：撤销其渲染回调与交互工具，并调用 `teardown`。
+     * 注意：`components` 里注册的类型**保留**（反序列化可能仍依赖，且撤销会让已存数据失效）。
+     */
+    unuse(name: string): boolean;
+    /** 已注册插件名（只读快照）。 */
+    getPlugins(): string[];
+    /**
+     * 更新选中集合的**统一入口**：写 `selectionList` 并同步插件工具。
+     * 约定：目前插件工具按「首个选中组件」匹配（引擎当前也仅支持单选）。
+     *
+     * @returns 是否有「排他」插件工具命中 —— 调用方据此禁用内置变换/连线面板
+     */
+    setSelection(components: Array<any> | any | null): boolean;
+    /**
+     * 无障碍：取「可访问节点快照」，供应用层渲染隐藏 DOM 镜像（screen reader / 键盘导航）。
+     *
+     * 引擎**不**自建 DOM 镜像层 —— 镜像的 DOM 结构、ARIA 属性、文案与焦点环高度依赖具体产品语义。
+     * 引擎负责给出：id / 角色建议 / 可读名称 / **屏幕坐标盒（CSS 像素）** / 层级 / tab 顺序 / 选中态；
+     * 应用层据此渲染 `<div role="img" aria-label=... style="position:absolute; ...">` 之类的镜像元素，
+     * 并用 `setFocusedComponent()` 把 DOM 焦点映射回组件。
+     *
+     * 不含未上屏（无有效变换矩阵）的组件，也不会修改任何组件 state。
+     */
+    getAccessibilityTree(options?: ICEAccessibilityOptions): ICEAccessibleNode[];
+    /**
+     * 设置键盘事件的焦点组件（无障碍 / 键盘导航原语）。
+     *
+     * 未设置时维持既有行为：键盘事件派发给「上次点击命中的组件」。
+     * 传入 id 字符串或组件实例；传 null / undefined 清除焦点。
+     */
+    setFocusedComponent(component: any | string | null): this;
+    /** 当前键盘焦点组件（未设置时为 null）。 */
+    getFocusedComponent(): any;
+    /**
+     * @method getType 获取组件构造函数
+     * @param className
+     * @returns
+     */
+    getType(className: string): any;
+    /**
+     * 加载自定义字体（平台适配）：浏览器走 FontFace API，小程序走 wx.loadFont。
+     * 加载后，在 ICEText 的 style.fontFamily 里引用该字体名即可。
+     * @param family 字体族名（如 'MyFont'）
+     * @param source 字体源（浏览器为 url/二进制，小程序为本地文件路径）
+     */
+    loadFont(family: string, source: string): Promise<any>;
+    /**
+     * 切换主题（string 按名切换 / object 浅合并 semantic），预设样式（preset）会自动跟随主题变量。
+     * 热切换：已渲染的组件里用了 preset 的会重新 resolve（用户显式传的样式优先）。
+     */
+    setTheme(theme: string | Partial<ICESemanticTheme>): this;
+    /**
+     * 设置视口（视图缩放 + 平移）。
+     *
+     * 屏幕坐标 = 世界坐标 * scale + translate。这是「视图缩放」，不改变任何组件的 state，
+     * 只影响渲染结果与命中检测的坐标换算。视口变化会让渲染器回退一次全量重绘并重建快照。
+     */
+    setViewport(scale: number, tx?: number, ty?: number): this;
+    /** 屏幕坐标（canvas 像素）→ 世界坐标（受视口逆变换）。 */
+    screenToWorld(sx: number, sy: number): [number, number];
+    /** 世界坐标 → 屏幕坐标（canvas 像素）。 */
+    worldToScreen(wx: number, wy: number): [number, number];
+    /**
+     * 刷新 canvas 的 getBoundingClientRect 缓存并返回。
+     *
+     * 输入事件用它把屏幕坐标换算成 canvas 内坐标；页面滚动 / 布局变化后必须刷新，
+     * 否则命中检测会整体偏移（旧实现只在 init 时取一次，滚动后即失效）。
+     * 高频的移动类事件复用缓存，见 DOMEventDispatcher.__resolveCanvasRect。
+     */
+    /**
+     * 渲染用视口 = dpr · viewport（仅「往画布上画」这一侧需要乘 dpr）。
+     * dpr === 1 时**直接返回 viewport 本身**：零分配、且与既有行为逐字节一致。
+     */
+    getRenderViewport(): {
+        scale: number;
+        tx: number;
+        ty: number;
+    };
+    /**
+     * 把 canvas 的 backing store 放大到 cssSize * dpr，并把 CSS 尺寸固定为逻辑尺寸。
+     * 只有传了 dpr>1 才会调用。
+     */
+    private __applyDevicePixelRatio;
+    updateCanvasBoundingRect(): any;
+    /**
+     * 读取 canvas 内容盒：把 border-box 的 rect 补偿成「绘制区」的偏移与尺寸。
+     * 无 getComputedStyle 的运行时（如小程序）补偿为 0，退回 rect 原值。
+     */
+    private __readContentBox;
+    /**
+     * 供输入派发器做坐标换算的矩形：**内容盒左上角**。
+     * 这样 `clientX - left` 就落在绘制区坐标里，与旧实现（offsetX）语义一致，不受 border/padding 影响。
+     */
+    getInputRect(): any;
+    /**
+     * 以屏幕点为锚点缩放视口（滚轮缩放 / 双指缩放可用的引擎原语）。
+     *
+     * 保持锚点下的世界坐标在缩放前后落在同一屏幕位置：先取锚点对应的世界坐标，
+     * 换算新 scale 后反解 translate。只改视口状态，**不修改任何组件的 state**
+     * （与 setViewport 同一约束）。
+     *
+     * 用法（应用层接滚轮，一行即可）：
+     * ```js
+     * ice.evtBus.on('wheel', (e) => {
+     *   ice.zoomAt(e.offsetX, e.offsetY, e.deltaY < 0 ? 1.1 : 1 / 1.1);
+     * });
+     * ```
+     *
+     * @param screenX 锚点屏幕 x（canvas 像素，通常是鼠标 / 触摸位置）
+     * @param screenY 锚点屏幕 y
+     * @param factor  缩放倍数，>1 放大、<1 缩小；非正数或非有限值直接忽略
+     * @param minScale 最小 scale（默认 0.05）
+     * @param maxScale 最大 scale（默认 20）
+     */
+    zoomAt(screenX: number, screenY: number, factor: number, minScale?: number, maxScale?: number): this;
+    /**
+     * 命中检测：屏幕坐标（canvas 像素）→ 命中的最上层可交互组件；无命中返回 null。
+     * 供应用层做「空白处拖拽平移 / 点击命中」等视口交互。
+     */
+    hitTest(sx: number, sy: number): any;
+    /**
+     * 注册命名主题（运行时注入，如多品牌 / 多租户 / 暗色主题）。
+     */
+    registerTheme(name: string, theme: ICETheme): this;
+    /**
+     * 获取当前主题对象（{ base, semantic }）。返回的是**本实例**的主题。
+     */
+    getTheme(): ICETheme;
+    /**
+     * 遍历组件树，对每个用了 preset 的组件重新 resolve preset（主题热切换）。
+     */
+    private __reapplyPresets;
+    /**
+     * 创建线性渐变对象，供组件 style.fillStyle/strokeStyle 使用。
+     * 用法：const g = ice.createLinearGradient(0,0,100,0); g.addColorStop(0,'red'); g.addColorStop(1,'blue');
+     *       new ICERect({ style: { fillStyle: g } })
+     */
+    createLinearGradient(x0: number, y0: number, x1: number, y1: number): any;
+    /**
+     * 创建径向（圆形）渐变对象。
+     */
+    createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, r1: number): any;
+    /**
+     * 创建锥形渐变（较新 API，Chrome 99+），不支持的环境返回 null。
+     */
+    createConicGradient(startAngle: number, x: number, y: number): any;
+    /**
+     * 创建图案填充（用图片平铺），供 style.fillStyle/strokeStyle 使用。
+     * @param image 图片源（HTMLImageElement/canvas 等）
+     * @param repetition 'repeat'|'repeat-x'|'repeat-y'|'no-repeat'
+     */
+    createPattern(image: any, repetition: string): any;
+    /**
+     * 读取画布指定区域的像素数据（取色、滤镜、橡皮擦等）。
+     */
+    getImageData(x: number, y: number, w: number, h: number): any;
+    /**
+     * 写入像素数据到画布。
+     */
+    putImageData(imageData: any, x: number, y: number): void;
+    createImageData(w: number, h: number): any;
+    /**
+     * 把画布导出为 dataURL（默认 PNG）。type 如 'image/png'/'image/jpeg'，quality 0~1（jpeg）。
+     */
+    toDataURL(type?: string, quality?: number): string;
+    /**
+     * 把画布导出为 Blob（回调接收）。
+     */
+    toBlob(callback: (blob: Blob | null) => void, type?: string, quality?: number): void;
+    /**
+     * 把对象序列化成 JSON 字符串：
+     * - 容器型组件需要负责子节点的序列化操作
+     * - 如果组件不需要序列化，需要返回 null
+     * @returns Object
+     */
+    toJSONString(): string;
+    /**
+     * 把对象序列化成 JSON 对象：
+     * - 容器型组件需要负责子节点的序列化操作
+     * - 如果组件不需要序列化，需要返回 null
+     * @returns Object
+     */
+    toJSONObject(): object;
+    fromJSONObject(jsonObject: any): void;
+    fromJSONString(jsonStr: string): void;
+}
+export default ICE;

package/dist/types/a11y/accessibility.d.mts

@@ -0,0 +1,46 @@
+/** 可访问节点的角色建议（应用层可映射为 role / 元素类型）。 */
+export type ICEAccessibleRole = 'graphic' | 'container' | 'link' | 'text' | 'image' | 'tool';
+export interface ICEAccessibleNode {
+    /** 组件 id（`props.id`） */
+    id: string;
+    /** 角色建议 */
+    role: ICEAccessibleRole;
+    /** 可读名称：优先 `state.ariaLabel`，其次文本内容，最后回退 id */
+    label: string;
+    /** 屏幕坐标盒（CSS 像素，已含视口换算），应用层可直接用于绝对定位 */
+    box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** 在 canvas 内是否可见（`display !== false`） */
+    visible: boolean;
+    /** 是否参与交互（`interactive`）——决定 DOM 上是否可点击/可聚焦 */
+    interactive: boolean;
+    /** 是否建议可聚焦（可见 + 可交互） */
+    focusable: boolean;
+    /** 建议的 tab 顺序（按 zIndex 升序，从 0 开始） */
+    tabIndex: number;
+    /** 是否当前被选中 */
+    selected: boolean;
+    /** 树层级（根为 1） */
+    level: number;
+    /** 父组件 id（顶层为 null） */
+    parentId: string | null;
+}
+export interface ICEAccessibilityOptions {
+    /** 是否包含工具层（控制面板等）。默认 false —— 工具层通常不应出现在无障碍树里。 */
+    includeTools?: boolean;
+    /** 是否包含不可见组件。默认 false。 */
+    includeHidden?: boolean;
+    /** 只保留该谓词返回 true 的组件（在其它过滤之后应用）。 */
+    filter?: (component: any) => boolean;
+}
+/**
+ * 构建可访问节点快照。
+ *
+ * 顺序：按「树深度优先 + 同级 zIndex 升序」，与视觉堆叠顺序一致（应用可据此生成 tab 顺序）。
+ * 不含未上屏（无有效变换矩阵）的组件。
+ */
+export declare function buildAccessibilityTree(ice: any, options?: ICEAccessibilityOptions): ICEAccessibleNode[];

package/dist/types/a11y/accessibility.d.ts

@@ -0,0 +1,46 @@
+/** 可访问节点的角色建议（应用层可映射为 role / 元素类型）。 */
+export type ICEAccessibleRole = 'graphic' | 'container' | 'link' | 'text' | 'image' | 'tool';
+export interface ICEAccessibleNode {
+    /** 组件 id（`props.id`） */
+    id: string;
+    /** 角色建议 */
+    role: ICEAccessibleRole;
+    /** 可读名称：优先 `state.ariaLabel`，其次文本内容，最后回退 id */
+    label: string;
+    /** 屏幕坐标盒（CSS 像素，已含视口换算），应用层可直接用于绝对定位 */
+    box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** 在 canvas 内是否可见（`display !== false`） */
+    visible: boolean;
+    /** 是否参与交互（`interactive`）——决定 DOM 上是否可点击/可聚焦 */
+    interactive: boolean;
+    /** 是否建议可聚焦（可见 + 可交互） */
+    focusable: boolean;
+    /** 建议的 tab 顺序（按 zIndex 升序，从 0 开始） */
+    tabIndex: number;
+    /** 是否当前被选中 */
+    selected: boolean;
+    /** 树层级（根为 1） */
+    level: number;
+    /** 父组件 id（顶层为 null） */
+    parentId: string | null;
+}
+export interface ICEAccessibilityOptions {
+    /** 是否包含工具层（控制面板等）。默认 false —— 工具层通常不应出现在无障碍树里。 */
+    includeTools?: boolean;
+    /** 是否包含不可见组件。默认 false。 */
+    includeHidden?: boolean;
+    /** 只保留该谓词返回 true 的组件（在其它过滤之后应用）。 */
+    filter?: (component: any) => boolean;
+}
+/**
+ * 构建可访问节点快照。
+ *
+ * 顺序：按「树深度优先 + 同级 zIndex 升序」，与视觉堆叠顺序一致（应用可据此生成 tab 顺序）。
+ * 不含未上屏（无有效变换矩阵）的组件。
+ */
+export declare function buildAccessibilityTree(ice: any, options?: ICEAccessibilityOptions): ICEAccessibleNode[];

package/dist/types/animation/AnimationManager.d.mts

@@ -0,0 +1,96 @@
+import ICEComponent from '../graphic/ICEComponent.mjs';
+import ICE from '../ICE.mjs';
+/**
+ * @class AnimationManager
+ *
+ * 动画管理器
+ *
+ * - 全局单例，一个 ICE 实例上只能有一个 AnimationManager 的实例。
+ *
+ * @singleton
+ * @see ICE
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class AnimationManager {
+    private animationMap;
+    private ice;
+    private paused;
+    private pausedAt;
+    private warned;
+    constructor(ice: ICE);
+    start(): this;
+    stop(): this;
+    private frameEventHandler;
+    /**
+     * 把值按点路径写入目标对象（支持 `transform.rotate` / `style.globalAlpha` 这类嵌套字段）。
+     *
+     * 旧实现直接 `newState[key] = value`，键里的点会被当成**字面量键名**，
+     * 于是 `animations: { 'transform.rotate': ... }` 静默失效（既不报错也不生效）。
+     * 多段路径共用同一父级时会逐段合并（`transform.rotate` 与 `transform.scale` 不互相覆盖）。
+     */
+    private __writeValue;
+    /**
+     * 每一帧推进动画：计算各属性的取值。
+     *
+     * 支持三种配置形态（同一组件上可混用）：
+     * 1. 单段补间：`{ from, to, duration }`
+     * 2. 关键帧时间轴：`{ keyframes: [{ offset, value, easing? }], duration }`
+     *    - `offset` 为 0~1 的时间占比，缺省时按数组顺序均分，超出 [0,1] 会被夹紧；
+     *    - `easing` 写在**段起始关键帧**上，作用于「该帧 → 下一帧」这一段；未写则用动画级 `easing`；
+     *    - 时间轴之外的取值分别是首帧 / 末帧的值（保持，不外推）。
+     * 3. 缓动可用主题 motion token 语义名（`duration: 'normal'` / `easing: 'out'`）或 EasingProgress 方法名。
+     *
+     * 取值可以是**数值**，也可以是**等长的数字数组**（`transform.scale` / `transform.translate` /
+     * `transform.skew` 等逐元素补间）。
+     *
+     * 结束判定按**已流逝时间**而非「值是否越过 to」：弹簧类缓动中途会过冲（越过 to 再回落），
+     * 若按值判定，第一帧过冲就会被误判成结束、动画提前停在过冲点上。
+     */
+    private tween;
+    /** 取进度 p 处的值：单段在 from→to 之间插值；关键帧按段插值（段内进度再经该段缓动）。 */
+    private __sampleValue;
+    /** 按进度 p 在 from/to 之间插值：数值直接线性，等长数字数组逐元素。 */
+    private __interpolate;
+    /** 补间取值是否合法：都是数字，或都是**等长**的数字数组。 */
+    private __isTweenable;
+    /** 取值种类：number | array（非空且全为数字） | null（不支持）。 */
+    private __valueKind;
+    /** 归一化关键帧到 animation.__frames（只做一次）：夹紧 offset、排序、校验各帧取值同型。 */
+    private __normalizeKeyframes;
+    /** 解析缓动名 → 归一化进度函数；未知名称回退 linear 并只提示一次。 */
+    private __easingFn;
+    /** round: true 时对补间结果取整（数组逐元素）。 */
+    private __roundIfNeeded;
+    /** 供告警信息使用的取值描述。 */
+    private __describe;
+    /** 拒绝一个非法的动画配置：标记结束（不再每帧重试）并只提示一次。 */
+    private __reject;
+    /** 同一个动画配置只告警一次，避免非法配置每帧刷屏。 */
+    private __warnOnce;
+    /**
+     * 把动画配置里的 motion token 语义名解析成实际值（首次触发时执行，结果写回 animation 对象缓存）：
+     * - duration: 'fast' | 'normal' | 'slow' | 'slower' → 主题 motion.duration 里的 ms。
+     * - easing: 'linear' | 'out' | 'inOut' | 'outQuart' | 'spring' | 'springSoft' | 'springSnappy'
+     *   → 主题 motion.easing 里的缓动方法名。
+     * 若传的是数字/已存在的 Easing 方法名，则原样保留（向后兼容）。
+     */
+    private __resolveMotion;
+    /**
+     * 判断动画到达终点后是否重复播放：
+     * - loop === true：无限循环；
+     * - iterationCount > 1：剩余次数递减，直到 1 次后结束。
+     */
+    private shouldRepeat;
+    /**
+     * 暂停所有动画（冻结进度，恢复时从暂停处继续）。
+     */
+    pause(): void;
+    /**
+     * 恢复所有动画：把每个动画的 startTime 往后移，抵消暂停期间的流逝。
+     */
+    resume(): void;
+    isPaused(): boolean;
+    add(component: ICEComponent): void;
+    remove(el: any): void;
+}
+export default AnimationManager;