ice-render 2.2.0 → 2.3.1

package/dist/types/graphic/container/ICEGroup.d.mts

@@ -97,7 +97,9 @@ declare class ICEGroup extends ICERect {
      * setState 仅仅修改参数，不会立即导致重新渲染，需要等待 FrameManager 调度，最小延迟时间约为 1/60=16.67 ms 。
      * @param newState
      */
-    setState(newState: any): void;
+    setState(newState: any, options?: {
+        paramsDirty?: boolean;
+    }): void;
     /**
      * @overwrite
      * @method destory

package/dist/types/graphic/container/ICEGroup.d.ts

@@ -97,7 +97,9 @@ declare class ICEGroup extends ICERect {
      * setState 仅仅修改参数，不会立即导致重新渲染，需要等待 FrameManager 调度，最小延迟时间约为 1/60=16.67 ms 。
      * @param newState
      */
-    setState(newState: any): void;
+    setState(newState: any, options?: {
+        paramsDirty?: boolean;
+    }): void;
     /**
      * @overwrite
      * @method destory

package/dist/types/graphic/link/ICEPolyLine.d.mts

@@ -15,6 +15,12 @@ import ICEDotPath from '../ICEDotPath.mjs';
  * @author 大漠穷秋<damoqiongqiu@126.com>
  */
 declare class ICEPolyLine extends ICEDotPath {
+    /**
+     * 折线的「动画安全键」**不能**沿用基类那套：`setState({left})` 会就地平移 `points`，
+     * 而折线的 width/height 是从点集推出来的 —— 位置对它来说是**几何**，必须走 `paramsDirty`。
+     * 这里只放行纯绘制/容器语义的键。
+     */
+    static readonly ANIMATION_SAFE_KEYS: readonly string[];
     /**
      * 类型标识
      * 用来解决 TypeScript 的 instanceof 兼容性问题， https://github.com/microsoft/TypeScript/issues/22585
@@ -209,7 +215,9 @@ declare class ICEPolyLine extends ICEDotPath {
      * @overwrite
      * @param newState 新的状态
      */
-    setState(newState: any): void;
+    setState(newState: any, options?: {
+        paramsDirty?: boolean;
+    }): void;
     /**
      * 插槽方向 → 单位方向向量（T=上/B=下/L=左/R=右，其余为无方向）。
      *

package/dist/types/graphic/link/ICEPolyLine.d.ts

@@ -15,6 +15,12 @@ import ICEDotPath from '../ICEDotPath';
  * @author 大漠穷秋<damoqiongqiu@126.com>
  */
 declare class ICEPolyLine extends ICEDotPath {
+    /**
+     * 折线的「动画安全键」**不能**沿用基类那套：`setState({left})` 会就地平移 `points`，
+     * 而折线的 width/height 是从点集推出来的 —— 位置对它来说是**几何**，必须走 `paramsDirty`。
+     * 这里只放行纯绘制/容器语义的键。
+     */
+    static readonly ANIMATION_SAFE_KEYS: readonly string[];
     /**
      * 类型标识
      * 用来解决 TypeScript 的 instanceof 兼容性问题， https://github.com/microsoft/TypeScript/issues/22585
@@ -209,7 +215,9 @@ declare class ICEPolyLine extends ICEDotPath {
      * @overwrite
      * @param newState 新的状态
      */
-    setState(newState: any): void;
+    setState(newState: any, options?: {
+        paramsDirty?: boolean;
+    }): void;
     /**
      * 插槽方向 → 单位方向向量（T=上/B=下/L=左/R=右，其余为无方向）。
      *

package/dist/types/graphic/shape/ICEEllipse.d.mts

@@ -24,6 +24,8 @@ declare class ICEEllipse extends ICEPath {
      * @overwrite
      * @param newState
      */
-    setState(newState: any): void;
+    setState(newState: any, options?: {
+        paramsDirty?: boolean;
+    }): void;
 }
 export default ICEEllipse;

package/dist/types/graphic/shape/ICEEllipse.d.ts

@@ -24,6 +24,8 @@ declare class ICEEllipse extends ICEPath {
      * @overwrite
      * @param newState
      */
-    setState(newState: any): void;
+    setState(newState: any, options?: {
+        paramsDirty?: boolean;
+    }): void;
 }
 export default ICEEllipse;

package/dist/types/graphic/shape/ICEIsogon.d.mts

@@ -47,6 +47,8 @@ declare class ICEIsogon extends ICEDotPath {
      * - 如果 setState 时仅仅指定 width 参数，则 radius 会被重新计算，如果仅仅指定了 height 参数，则 radius 会被重新计算。
      * @param newState
      */
-    setState(newState: any): void;
+    setState(newState: any, options?: {
+        paramsDirty?: boolean;
+    }): void;
 }
 export default ICEIsogon;

package/dist/types/graphic/shape/ICEIsogon.d.ts

@@ -47,6 +47,8 @@ declare class ICEIsogon extends ICEDotPath {
      * - 如果 setState 时仅仅指定 width 参数，则 radius 会被重新计算，如果仅仅指定了 height 参数，则 radius 会被重新计算。
      * @param newState
      */
-    setState(newState: any): void;
+    setState(newState: any, options?: {
+        paramsDirty?: boolean;
+    }): void;
 }
 export default ICEIsogon;

package/dist/types/graphic/shape/ICERose.d.mts

@@ -36,6 +36,8 @@ declare class ICERose extends ICEDotPath {
      * - 如果 setState 时仅仅指定 width 参数，则 radius 会被重新计算，如果仅仅指定了 height 参数，则 radius 会被重新计算。
      * @param newState
      */
-    setState(newState: any): void;
+    setState(newState: any, options?: {
+        paramsDirty?: boolean;
+    }): void;
 }
 export default ICERose;

package/dist/types/graphic/shape/ICERose.d.ts

@@ -36,6 +36,8 @@ declare class ICERose extends ICEDotPath {
      * - 如果 setState 时仅仅指定 width 参数，则 radius 会被重新计算，如果仅仅指定了 height 参数，则 radius 会被重新计算。
      * @param newState
      */
-    setState(newState: any): void;
+    setState(newState: any, options?: {
+        paramsDirty?: boolean;
+    }): void;
 }
 export default ICERose;

package/dist/types/graphic/shape/ICEStar.d.mts

@@ -40,6 +40,8 @@ declare class ICEStar extends ICEDotPath {
      * - 如果 setState 时仅仅指定 width 参数，则 radius 会被重新计算，如果仅仅指定了 height 参数，则 radius 会被重新计算。
      * @param newState
      */
-    setState(newState: any): void;
+    setState(newState: any, options?: {
+        paramsDirty?: boolean;
+    }): void;
 }
 export default ICEStar;

package/dist/types/graphic/shape/ICEStar.d.ts

@@ -40,6 +40,8 @@ declare class ICEStar extends ICEDotPath {
      * - 如果 setState 时仅仅指定 width 参数，则 radius 会被重新计算，如果仅仅指定了 height 参数，则 radius 会被重新计算。
      * @param newState
      */
-    setState(newState: any): void;
+    setState(newState: any, options?: {
+        paramsDirty?: boolean;
+    }): void;
 }
 export default ICEStar;

package/dist/types/graphic/text/ICEText.d.mts

@@ -5,6 +5,12 @@ import ICEComponent from '../ICEComponent.mjs';
  * @author 大漠穷秋<damoqiongqiu@126.com>
  */
 declare class ICEText extends ICEComponent {
+    /**
+     * 文本的「动画安全键」：基类那批（位置/变换/透明度/显示/zIndex）之外，再放行**不参与量测**的
+     * 绘制类与编辑类键；字号/字间距/行高/内边距/`font*`/文本内容/换行参数一概**不在**白名单里
+     * （它们都会改变盒子尺寸或换行结果 → 必须走 `paramsDirty`）。
+     */
+    static readonly ANIMATION_SAFE_KEYS: readonly string[];
     /**
      * @cfg
      * {

package/dist/types/graphic/text/ICEText.d.ts

@@ -5,6 +5,12 @@ import ICEComponent from '../ICEComponent';
  * @author 大漠穷秋<damoqiongqiu@126.com>
  */
 declare class ICEText extends ICEComponent {
+    /**
+     * 文本的「动画安全键」：基类那批（位置/变换/透明度/显示/zIndex）之外，再放行**不参与量测**的
+     * 绘制类与编辑类键；字号/字间距/行高/内边距/`font*`/文本内容/换行参数一概**不在**白名单里
+     * （它们都会改变盒子尺寸或换行结果 → 必须走 `paramsDirty`）。
+     */
+    static readonly ANIMATION_SAFE_KEYS: readonly string[];
     /**
      * @cfg
      * {

package/dist/types/index.d.mts

@@ -6,6 +6,13 @@
  *
  */
 export { default as AnimationManager } from './animation/AnimationManager.mjs';
+export { validateAnimations, classifyAnimationValue, isInterpolatablePair, ICE_ANIMATION_DIAGNOSTIC_CODES, } from './animation/validate-animations.mjs';
+export { registerEasing, unregisterEasing, resolveEasing, easingNames, customEasingNames, } from './animation/easing-registry.mjs';
+export { default as AnimationTimeline } from './animation/AnimationTimeline.mjs';
+export type { TimelineOptions } from './animation/AnimationTimeline.mjs';
+export { EasingProgress } from './animation/Easing.mjs';
+export { classifyValue as classifyAnimationValueKind, interpolateValue as interpolateAnimationValue, isInterpolatable as isAnimationValueInterpolatable, parseColor, parseNumberWithUnit, } from './animation/interpolators.mjs';
+export type { ICEAnimationDiagnostic, ICEAnimationDiagnosticCode, ValidateAnimationsOptions, } from './animation/validate-animations.mjs';
 export { default as ICEControlPanel } from './control-panel/ICEControlPanel.mjs';
 export { default as ICEControlPanelManager } from './control-panel/ICEControlPanelManager.mjs';
 export { default as AlignmentGuideManager } from './control-panel/AlignmentGuideManager.mjs';
@@ -51,6 +58,8 @@ export { default as ICE } from './ICE.mjs';
 export { default as CanvasRenderer } from './renderer/CanvasRenderer.mjs';
 export { exportSvg, exportSvgResult } from './export/SvgExporter.mjs';
 export type { SvgExportOptions, SvgExportResult } from './export/SvgExporter.mjs';
+export { composeLayersToCanvas, composeLayersDataURL } from './export/compose-layers.mjs';
+export type { ComposeLayersOptions } from './export/compose-layers.mjs';
 export { default as PluginHost } from './plugin/PluginHost.mjs';
 export type { ICEPlugin, ICEPluginTool, ICERenderHook, ICERenderFrame } from './plugin/PluginHost.mjs';
 export { default as Serializer, SERIALIZATION_VERSION } from './persistence/Serializer.mjs';

package/dist/types/index.d.ts

@@ -6,6 +6,13 @@
  *
  */
 export { default as AnimationManager } from './animation/AnimationManager';
+export { validateAnimations, classifyAnimationValue, isInterpolatablePair, ICE_ANIMATION_DIAGNOSTIC_CODES, } from './animation/validate-animations';
+export { registerEasing, unregisterEasing, resolveEasing, easingNames, customEasingNames, } from './animation/easing-registry';
+export { default as AnimationTimeline } from './animation/AnimationTimeline';
+export type { TimelineOptions } from './animation/AnimationTimeline';
+export { EasingProgress } from './animation/Easing';
+export { classifyValue as classifyAnimationValueKind, interpolateValue as interpolateAnimationValue, isInterpolatable as isAnimationValueInterpolatable, parseColor, parseNumberWithUnit, } from './animation/interpolators';
+export type { ICEAnimationDiagnostic, ICEAnimationDiagnosticCode, ValidateAnimationsOptions, } from './animation/validate-animations';
 export { default as ICEControlPanel } from './control-panel/ICEControlPanel';
 export { default as ICEControlPanelManager } from './control-panel/ICEControlPanelManager';
 export { default as AlignmentGuideManager } from './control-panel/AlignmentGuideManager';
@@ -51,6 +58,8 @@ export { default as ICE } from './ICE';
 export { default as CanvasRenderer } from './renderer/CanvasRenderer';
 export { exportSvg, exportSvgResult } from './export/SvgExporter';
 export type { SvgExportOptions, SvgExportResult } from './export/SvgExporter';
+export { composeLayersToCanvas, composeLayersDataURL } from './export/compose-layers';
+export type { ComposeLayersOptions } from './export/compose-layers';
 export { default as PluginHost } from './plugin/PluginHost';
 export type { ICEPlugin, ICEPluginTool, ICERenderHook, ICERenderFrame } from './plugin/PluginHost';
 export { default as Serializer, SERIALIZATION_VERSION } from './persistence/Serializer';

package/dist/types/util/data-util.d.mts

@@ -41,3 +41,13 @@ export declare function flattenAllComponents(ice: any, result?: any[]): any[];
  */
 export declare function hitTestComponents(ice: any, wx: number, wy: number, tolerance: number): any;
 export declare function flattenTree(result?: any[], childNodes?: any[], level?: number, pid?: any): any[];
+/**
+ * 把组件**连同整棵子树**重新绑定到指定 `ICE` 实例（`ice/ctx/evtBus/root`）。
+ *
+ * 为什么需要单独一个工具：`ICEGroup` 的子树同步钩子是 `once(AFTER_ADD, afterAddHandler)` ——
+ * 只在**首次挂载**时同步一次；跨实例迁移 / 嵌套重父级（`moveComponentTo` / `adoptChild`）时，
+ * 已经添加过的容器不会再触发它，后代就会把事件发到旧实例上（表现为"搬过去之后点不动/动画不动"）。
+ *
+ * 迭代实现（不用递归，深树也不会爆栈）；幂等，可安全重复调用。
+ */
+export declare function rebindComponentTree(component: any, ice: any): void;

package/dist/types/util/data-util.d.ts

@@ -41,3 +41,13 @@ export declare function flattenAllComponents(ice: any, result?: any[]): any[];
  */
 export declare function hitTestComponents(ice: any, wx: number, wy: number, tolerance: number): any;
 export declare function flattenTree(result?: any[], childNodes?: any[], level?: number, pid?: any): any[];
+/**
+ * 把组件**连同整棵子树**重新绑定到指定 `ICE` 实例（`ice/ctx/evtBus/root`）。
+ *
+ * 为什么需要单独一个工具：`ICEGroup` 的子树同步钩子是 `once(AFTER_ADD, afterAddHandler)` ——
+ * 只在**首次挂载**时同步一次；跨实例迁移 / 嵌套重父级（`moveComponentTo` / `adoptChild`）时，
+ * 已经添加过的容器不会再触发它，后代就会把事件发到旧实例上（表现为"搬过去之后点不动/动画不动"）。
+ *
+ * 迭代实现（不用递归，深树也不会爆栈）；幂等，可安全重复调用。
+ */
+export declare function rebindComponentTree(component: any, ice: any): void;

package/dist/types/util/errors.d.mts

@@ -45,6 +45,10 @@ export declare const ICE_ERROR_CODES: {
     readonly OFFSCREEN_CONTEXT_UNSUPPORTED: "ICE_OFFSCREEN_CONTEXT_UNSUPPORTED";
     /** 当前运行时没有可用的离屏 canvas。 */
     readonly OFFSCREEN_CANVAS_UNSUPPORTED: "ICE_OFFSCREEN_CANVAS_UNSUPPORTED";
+    /** `registerEasing()` 的名字/函数非法。 */
+    readonly ANIM_EASING_INVALID: "ICE_ANIM_EASING_INVALID";
+    /** `registerEasing()` 的名字已被内置缓动占用，或重复注册。 */
+    readonly ANIM_EASING_NAME_CONFLICT: "ICE_ANIM_EASING_NAME_CONFLICT";
 };
 export type ICEErrorCode = (typeof ICE_ERROR_CODES)[keyof typeof ICE_ERROR_CODES];
 export interface ICEErrorDetails {

package/dist/types/util/errors.d.ts

@@ -45,6 +45,10 @@ export declare const ICE_ERROR_CODES: {
     readonly OFFSCREEN_CONTEXT_UNSUPPORTED: "ICE_OFFSCREEN_CONTEXT_UNSUPPORTED";
     /** 当前运行时没有可用的离屏 canvas。 */
     readonly OFFSCREEN_CANVAS_UNSUPPORTED: "ICE_OFFSCREEN_CANVAS_UNSUPPORTED";
+    /** `registerEasing()` 的名字/函数非法。 */
+    readonly ANIM_EASING_INVALID: "ICE_ANIM_EASING_INVALID";
+    /** `registerEasing()` 的名字已被内置缓动占用，或重复注册。 */
+    readonly ANIM_EASING_NAME_CONFLICT: "ICE_ANIM_EASING_NAME_CONFLICT";
 };
 export type ICEErrorCode = (typeof ICE_ERROR_CODES)[keyof typeof ICE_ERROR_CODES];
 export interface ICEErrorDetails {

package/package.json

@@ -1,7 +1,7 @@
 {
   "author": "大漠穷秋",
   "name": "ice-render",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "description": "A canvas engine for interactive graphics.",
   "repository": {
     "type": "git",
@@ -51,7 +51,9 @@
     "pkg:check": "npm run pkg:lint && npm run pkg:types",
     "test:visual:ci": "playwright test e2e/visual/examples-smoke.spec.ts e2e/visual/interaction.spec.ts e2e/visual/dirty-rect-pixel.spec.ts e2e/visual/viewport.spec.ts e2e/visual/alignment.spec.ts e2e/visual/hidpi.spec.ts e2e/visual/worker-perf.spec.ts e2e/visual/svg-parity.spec.ts",
     "verify": "npm run lint && npm run types:check && npm run build && npm test -- --runInBand && npm run bench 2000 && npm run pkg:check",
-    "verify:full": "npm run verify && npm run test:visual"
+    "verify:full": "npm run verify && npm run test:visual && npm run bench:anim -- --check && npm run bench:layers -- --check",
+    "bench:anim": "node bench/anim/animation-bench.mjs",
+    "bench:layers": "node bench/layers/layering-bench.mjs"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",