ice-render 2.1.1 → 2.3.0

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

@@ -1,22 +1,38 @@
 import ICEComponent from '../graphic/ICEComponent';
 import ICE from '../ICE';
-/**
- * @class AnimationManager
- *
- * 动画管理器
- *
- * - 全局单例，一个 ICE 实例上只能有一个 AnimationManager 的实例。
- *
- * @singleton
- * @see ICE
- * @author 大漠穷秋<damoqiongqiu@126.com>
- */
+import { ICEAnimationDiagnostic } from './validate-animations';
+import AnimationTimeline from './AnimationTimeline';
 declare class AnimationManager {
     private animationMap;
     private ice;
     private paused;
     private pausedAt;
+    /**
+     * 飞行中的**平移**是否吸附到设备像素栅格（默认开）。
+     *
+     * 为什么需要它：离屏位图的纯平移复用（`ObjectCache.refreshPosition`）要求位移是**整数设备像素**，
+     * 否则会退化成每帧重建位图（实测 1000 个文本：可复用 2.5ms/帧 vs 重建 32~41ms/帧）。
+     * 吸附只作用于「纯平移 + 当前可离屏缓存」的组件，且**动画终点值永远精确写入**（配置 100.5 就落在 100.5）。
+     * 需要极致平滑的应用可以整体关掉（`ice.animationManager.snapToDevicePixel = false`），
+     * 或对单条动画写 `snapToDevicePixel: false`。
+     */
+    snapToDevicePixel: boolean;
+    /**
+     * 「减少动态效果」：用户系统偏好（`prefers-reduced-motion: reduce`）为真时，**动画直接落终点**
+     * （不播放位移/缩放过程），只保留最终状态 —— 这是无障碍上最保守、最可预期的语义。
+     *
+     * 默认在构造时读一次 `root.matchMedia`（无 DOM 运行时为 false）；应用层可用
+     * `ice.setReducedMotion(true/false)` 显式覆盖（也能接自己的偏好设置）。
+     */
+    reducedMotion: boolean;
     private warned;
+    /** 运行期诊断（见 getDiagnostics）：按 code|path 去重。 */
+    private __diagnostics;
+    private __diagnosticKeys;
+    /** 当前正在处理的属性路径（`__easingFn` 记诊断时要用，避免把 path 一层层传下去）。 */
+    private __currentPath;
+    /** 已告警过的回调异常（key|name），避免写错的回调每帧刷屏。 */
+    private __callbackWarned;
     constructor(ice: ICE);
     start(): this;
     stop(): this;
@@ -47,26 +63,84 @@ declare class AnimationManager {
      * 若按值判定，第一帧过冲就会被误判成结束、动画提前停在过冲点上。
      */
     private tween;
+    /**
+     * 动画写值通道：把本帧的新值提交给组件。
+     *
+     * 与直接 `setState` 的区别只有一点 —— **只在必要时才置 `paramsDirty`**：
+     * 本帧写出的键**全部**落在组件的「动画安全键」白名单里（纯绘制/变换）时跳过派生参数重算。
+     * 判定由组件自己给（`isAnimationSafeKey`），未声明白名单的组件/第三方组件一律走旧路径（每帧置脏）。
+     */
+    private __commitAnimationState;
+    /**
+     * 飞行中的**纯平移**吸附到设备像素栅格（`1 / 设备缩放` 的整数倍）。
+     *
+     * 三个前提缺一不可：① 实例开关打开且该动画没写 `snapToDevicePixel: false`；
+     * ② 键是纯平移（`left` / `top` / `transform.translate`）；③ 该组件当前**可离屏缓存**
+     * （只有这时吸附才换得来位图复用；无渲染器的运行时/测试替身自动跳过）。
+     */
+    private __snapTranslation;
+    /** 渲染视口的缩放（= dpr × 视口 scale）——设备像素与世界单位的换算比例。 */
+    private __deviceScale;
+    /** 该组件当前是否走离屏缓存（只有它才谈得上"位图纯平移复用"）。判定权在渲染器，这里只查询。 */
+    private __isBitmapReusable;
+    /** 数值按设备像素栅格吸附；数组逐元素（`transform.translate`）。 */
+    private __snapValue;
     /** 取进度 p 处的值：单段在 from→to 之间插值；关键帧按段插值（段内进度再经该段缓动）。 */
     private __sampleValue;
-    /** 按进度 p 在 from/to 之间插值：数值直接线性，等长数字数组逐元素。 */
+    /**
+     * 按进度 p 在 from/to 之间插值：数值 / 等长数字数组 / **颜色** / 带单位数字串
+     * （判定与求值都在 `interpolators.ts`，与校验器同源）。
+     */
     private __interpolate;
-    /** 补间取值是否合法：都是数字，或都是**等长**的数字数组。 */
+    /** 补间取值是否合法（数值 / 等长数字数组 / 颜色 / 同单位数字串）—— 判定见 interpolators。 */
     private __isTweenable;
-    /** 取值种类：number | array（非空且全为数字） | null（不支持）。 */
+    /** 取值种类（转发到插值器，保持既有私有方法名可用）。 */
     private __valueKind;
     /** 归一化关键帧到 animation.__frames（只做一次）：夹紧 offset、排序、校验各帧取值同型。 */
     private __normalizeKeyframes;
     /** 解析缓动名 → 归一化进度函数；未知名称回退 linear 并只提示一次。 */
     private __easingFn;
+    /** 动画方向（缺省 `'normal'`；非法的方向由 `validateAnimations` 在运行前拦住）。 */
+    private __directionOf;
+    /** 把缓动后的进度按方向映射：`reverse` 反转；`alternate` 在奇数轮反向（yoyo）。 */
+    private __applyDirection;
+    /** 本轮**起点**对应的进度（alternate 的奇数轮从另一端出发）。 */
+    private __roundStartProgress;
+    /** 本轮**终点**对应的进度。 */
+    private __roundEndProgress;
+    /** 回调上下文：给应用层足够信息做链式编排（不用再去读 state 反推进度）。 */
+    private __callbackContext;
+    /**
+     * 触发生命周期回调（`onStart` / `onUpdate` / `onRepeat` / `onComplete`）。
+     *
+     * 回调异常**绝不打断帧循环**（一个写错的回调不该让整个场景卡死）：吞掉异常、记一条
+     * `ICE_ANIM_CALLBACK_ERROR` 诊断并 `console.warn` 一次。
+     */
+    private __invokeCallback;
     /** round: true 时对补间结果取整（数组逐元素）。 */
     private __roundIfNeeded;
     /** 供告警信息使用的取值描述。 */
     private __describe;
-    /** 拒绝一个非法的动画配置：标记结束（不再每帧重试）并只提示一次。 */
+    /** 拒绝一个非法的动画配置：标记结束（不再每帧重试）、只提示一次，并记一条结构化诊断。 */
     private __reject;
-    /** 同一个动画配置只告警一次，避免非法配置每帧刷屏。 */
+    /**
+     * 记录一条诊断（`getDiagnostics()` 可读）并只 `console.warn` 一次，避免非法配置每帧刷屏。
+     *
+     * 诊断的 code / severity / path 与 `validateAnimations()` 同源：**运行期才发现被跳过的配置，
+     * 与编译期校验报出的是同一组码**，Agent / 应用层不需要学两套。
+     */
     private __warnOnce;
+    /** 记一条结构化诊断（按 `code|path` 去重；只留文本，不含动画对象本身）。 */
+    private __recordDiagnostic;
+    /**
+     * 运行期累积的动画诊断（非法配置被跳过 / 缓动回退时会记录）。
+     *
+     * 与 `validateAnimations()` 的分工：那个是**运行前**的纯校验（Agent / DSL 用），
+     * 这个是**运行中**真实发生过的拒绝与回退（应用层可上报 / 开发期断言）。
+     */
+    getDiagnostics(): ICEAnimationDiagnostic[];
+    /** 清空运行期诊断（测试 / 重新加载场景时用）。 */
+    clearDiagnostics(): void;
     /**
      * 把动画配置里的 motion token 语义名解析成实际值（首次触发时执行，结果写回 animation 对象缓存）：
      * - duration: 'fast' | 'normal' | 'slow' | 'slower' → 主题 motion.duration 里的 ms。
@@ -90,6 +164,33 @@ declare class AnimationManager {
      */
     resume(): void;
     isPaused(): boolean;
+    /**
+     * 是否有"还在推进"的动画（`ICE.needsFrame()` 用它决定要不要继续要帧）。
+     *
+     * 暂停时返回 false：暂停期间动画进度不推进，继续跑帧纯属空转（空闲停帧会因此把 rAF 停掉，
+     * 恢复时 `resume()` 会调整 startTime，进度从暂停处接上）。
+     */
+    hasActiveAnimations(): boolean;
+    /**
+     * 新建一条时间轴（编排多个组件/属性的时序）。见 `AnimationTimeline` 的文档与 18 §3。
+     *
+     * ```js
+     * ice.animationManager.timeline()
+     *   .add(cardA, { left: { from: 0, to: 100, duration: 400 } }, { at: 0 })
+     *   .add(cardB, { left: { from: 0, to: 100, duration: 400 } }, { at: '+=120' })
+     *   .play();
+     * ```
+     */
+    timeline(): AnimationTimeline;
+    /**
+     * 重播某个组件的全部动画：清掉运行时状态（startTime / finished / 轮次 / 降频节拍）后重新纳入管理。
+     *
+     * 与 `add()` 的区别：`add()` 只是"确保它在管理器的列表里"（跑完的动画不会自己重播），
+     * `replay()` 才是"从头再放一遍"。时间轴的 `restart()` 就是用它实现的。
+     */
+    replay(component: any): this;
+    /** 这个组件的动画现在还在推进吗（跑完 / 被 stop / 已从管理器摘除 → false）。 */
+    isAnimating(component: any): boolean;
     add(component: ICEComponent): void;
     remove(el: any): void;
 }

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

@@ -0,0 +1,77 @@
+/**
+ * 动画时间轴：把「谁、在什么时刻、动什么」组织成一条可播放/暂停/重播的轨道集合。
+ *
+ * 为什么要它：`props.animations` 是**每条属性各自为政**的（各自 duration / easing / 自己的 startTime），
+ * 表达"卡片 A 入场 → 200ms 后卡片 B 跟上 → 一起停住"这类编排时，应用只能手算 delay —— 这正是
+ * Agent / 低代码最不擅长的部分（算时间）。
+ *
+ * 设计取向（与 18 §3.1 的"不引入新时间模型"一致）：时间轴**不是新的求值器**，它只是调度器 ——
+ * `play()` 时把每条轨道折算成 `delay` 写进组件的 `props.animations`，剩下的推进仍由 `AnimationManager`
+ * 按帧/按时间完成。因此它与既有的缓动、关键帧、量化、缓存复用、空闲停帧完全兼容。
+ *
+ * ```js
+ * const timeline = ice.animationManager.timeline();
+ * timeline
+ *   .add(cardA, { 'transform.translate': { from: [-40, 0], to: [0, 0], duration: 400 } }, { at: 0 })
+ *   .add(cardB, { 'transform.translate': { from: [-40, 0], to: [0, 0], duration: 400 } }, { at: '+=120' })
+ *   .stagger(rows, { 'style.globalAlpha': { from: 0, to: 1, duration: 240 } }, { each: 60, at: 300 });
+ * timeline.play();
+ * // 点击重播：
+ * timeline.restart();
+ * ```
+ */
+import AnimationManager from './AnimationManager.mjs';
+export type TimelineOptions = {
+    /** 起始时刻：绝对毫秒，或 `'+=N'`（相对**上一条轨道**的时间） */
+    at?: number | string;
+    /** `stagger` 用：每条之间的间隔毫秒 */
+    each?: number;
+};
+export default class AnimationTimeline {
+    private manager;
+    private tracks;
+    private cursor;
+    private playing;
+    private paused;
+    private pending;
+    private finishedPromise;
+    private resolveFinished;
+    constructor(manager: AnimationManager);
+    /** 时间轴总时长（最后一条轨道的起始 + 它自己的时长；用于排版/展示）。 */
+    get duration(): number;
+    isPlaying(): boolean;
+    /** 全部轨道跑完时 resolve（`play()` 之前拿到的是同一个 Promise）。 */
+    get finished(): Promise<void>;
+    /**
+     * 加一条轨道：把 `config`（`{属性路径: 动画配置}`）合并进组件的 `props.animations`，
+     * 并记录这条轨道的起始时刻。
+     */
+    add(component: any, config: Record<string, any>, options?: TimelineOptions): this;
+    /**
+     * 错峰：同一份配置按 `each` 毫秒依次加到一组组件上（"卡片依次滑入"）。
+     * 返回 this 以便链式继续 `add`。
+     */
+    stagger(components: any[], config: Record<string, any>, options?: TimelineOptions): this;
+    /**
+     * 播放：把每条轨道注册进 `AnimationManager`（按 `at` 折算 delay）并唤醒帧循环。
+     * 重复调用是幂等的（已在播放则什么都不做）。
+     */
+    play(): this;
+    /** 暂停整条时间轴（等价于 `AnimationManager.pause()`）。 */
+    pause(): this;
+    /** 继续（从暂停处接上）。 */
+    resume(): this;
+    /**
+     * 停止：把本时间轴注册的动画从管理器里摘掉（还原 onComplete 包装），组件停在当前值。
+     */
+    stop(): this;
+    /**
+     * 重播：重置每条动画的运行时状态（startTime / finished / 轮次 / 降频节拍）后重新播放。
+     * 这是"点击重播"的直接入口。
+     */
+    restart(): this;
+    /** `'+=N'` → 游标 + N；数字 → 原值；非法 → 当前游标。 */
+    private __resolveAt;
+    private __onTrackKeyDone;
+    private __resolveIfDone;
+}

package/dist/types/animation/AnimationTimeline.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 动画时间轴：把「谁、在什么时刻、动什么」组织成一条可播放/暂停/重播的轨道集合。
+ *
+ * 为什么要它：`props.animations` 是**每条属性各自为政**的（各自 duration / easing / 自己的 startTime），
+ * 表达"卡片 A 入场 → 200ms 后卡片 B 跟上 → 一起停住"这类编排时，应用只能手算 delay —— 这正是
+ * Agent / 低代码最不擅长的部分（算时间）。
+ *
+ * 设计取向（与 18 §3.1 的"不引入新时间模型"一致）：时间轴**不是新的求值器**，它只是调度器 ——
+ * `play()` 时把每条轨道折算成 `delay` 写进组件的 `props.animations`，剩下的推进仍由 `AnimationManager`
+ * 按帧/按时间完成。因此它与既有的缓动、关键帧、量化、缓存复用、空闲停帧完全兼容。
+ *
+ * ```js
+ * const timeline = ice.animationManager.timeline();
+ * timeline
+ *   .add(cardA, { 'transform.translate': { from: [-40, 0], to: [0, 0], duration: 400 } }, { at: 0 })
+ *   .add(cardB, { 'transform.translate': { from: [-40, 0], to: [0, 0], duration: 400 } }, { at: '+=120' })
+ *   .stagger(rows, { 'style.globalAlpha': { from: 0, to: 1, duration: 240 } }, { each: 60, at: 300 });
+ * timeline.play();
+ * // 点击重播：
+ * timeline.restart();
+ * ```
+ */
+import AnimationManager from './AnimationManager';
+export type TimelineOptions = {
+    /** 起始时刻：绝对毫秒，或 `'+=N'`（相对**上一条轨道**的时间） */
+    at?: number | string;
+    /** `stagger` 用：每条之间的间隔毫秒 */
+    each?: number;
+};
+export default class AnimationTimeline {
+    private manager;
+    private tracks;
+    private cursor;
+    private playing;
+    private paused;
+    private pending;
+    private finishedPromise;
+    private resolveFinished;
+    constructor(manager: AnimationManager);
+    /** 时间轴总时长（最后一条轨道的起始 + 它自己的时长；用于排版/展示）。 */
+    get duration(): number;
+    isPlaying(): boolean;
+    /** 全部轨道跑完时 resolve（`play()` 之前拿到的是同一个 Promise）。 */
+    get finished(): Promise<void>;
+    /**
+     * 加一条轨道：把 `config`（`{属性路径: 动画配置}`）合并进组件的 `props.animations`，
+     * 并记录这条轨道的起始时刻。
+     */
+    add(component: any, config: Record<string, any>, options?: TimelineOptions): this;
+    /**
+     * 错峰：同一份配置按 `each` 毫秒依次加到一组组件上（"卡片依次滑入"）。
+     * 返回 this 以便链式继续 `add`。
+     */
+    stagger(components: any[], config: Record<string, any>, options?: TimelineOptions): this;
+    /**
+     * 播放：把每条轨道注册进 `AnimationManager`（按 `at` 折算 delay）并唤醒帧循环。
+     * 重复调用是幂等的（已在播放则什么都不做）。
+     */
+    play(): this;
+    /** 暂停整条时间轴（等价于 `AnimationManager.pause()`）。 */
+    pause(): this;
+    /** 继续（从暂停处接上）。 */
+    resume(): this;
+    /**
+     * 停止：把本时间轴注册的动画从管理器里摘掉（还原 onComplete 包装），组件停在当前值。
+     */
+    stop(): this;
+    /**
+     * 重播：重置每条动画的运行时状态（startTime / finished / 轮次 / 降频节拍）后重新播放。
+     * 这是"点击重播"的直接入口。
+     */
+    restart(): this;
+    /** `'+=N'` → 游标 + N；数字 → 原值；非法 → 当前游标。 */
+    private __resolveAt;
+    private __onTrackKeyDone;
+    private __resolveIfDone;
+}

package/dist/types/animation/easing-registry.d.mts

@@ -0,0 +1,37 @@
+/**
+ * 缓动注册表：内置缓动 + **应用层自定义缓动**。
+ *
+ * 为什么要开放这一层（用户目标②「应用层有机会自定义动画」）：
+ * 内置只有十几个 easing，产品想表达自己的手感（品牌回弹、机械式阶跃、物理曲线）时，
+ * 最自然的方式是**给一个函数**，而不是"只能从枚举里挑"。
+ *
+ * 用法：
+ * ```js
+ * ICE.registerEasing('brandSpring', (t) => 1 - Math.pow(1 - t, 3) * Math.cos(t * 6));
+ * new ICERect({ animations: { left: { from: 0, to: 100, duration: 400, easing: 'brandSpring' } } });
+ * // 也可以直接传函数（只对这一条动画生效，不用注册）：
+ * animations: { left: { from: 0, to: 100, duration: 400, easing: (t) => t * t } }
+ * ```
+ *
+ * 注册的**不覆盖内置**（内置是引擎契约的一部分，被偷偷替换会让同一份文档在不同应用里表现不同）；
+ * 重名注册会明确抛错（`ICE_ANIM_EASING_NAME_CONFLICT`）。
+ */
+import { EasingProgress } from './Easing.mjs';
+/**
+ * 注册一个自定义缓动。
+ *
+ * @param name 缓动名（非空字符串；不能与**内置**缓动重名，也不能重复注册同一个名字）
+ * @param fn   归一化进度函数 `(t) => number`
+ */
+export declare function registerEasing(name: string, fn: EasingProgress): void;
+/** 注销自定义缓动（内置缓动不可注销）；返回是否真的移除了。 */
+export declare function unregisterEasing(name: string): boolean;
+/**
+ * 解析缓动：**函数**原样返回（临时自定义）、字符串查内置 → 自定义；没有就返回 null
+ * （调用方决定是回退 linear 还是报错）。
+ */
+export declare function resolveEasing(nameOrFn: any): EasingProgress | null;
+/** 当前可用的缓动名（内置 + 自定义），用于校验提示与文档。 */
+export declare function easingNames(): string[];
+/** 只列出应用层注册的缓动名（调试 / 测试用）。 */
+export declare function customEasingNames(): string[];

package/dist/types/animation/easing-registry.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 缓动注册表：内置缓动 + **应用层自定义缓动**。
+ *
+ * 为什么要开放这一层（用户目标②「应用层有机会自定义动画」）：
+ * 内置只有十几个 easing，产品想表达自己的手感（品牌回弹、机械式阶跃、物理曲线）时，
+ * 最自然的方式是**给一个函数**，而不是"只能从枚举里挑"。
+ *
+ * 用法：
+ * ```js
+ * ICE.registerEasing('brandSpring', (t) => 1 - Math.pow(1 - t, 3) * Math.cos(t * 6));
+ * new ICERect({ animations: { left: { from: 0, to: 100, duration: 400, easing: 'brandSpring' } } });
+ * // 也可以直接传函数（只对这一条动画生效，不用注册）：
+ * animations: { left: { from: 0, to: 100, duration: 400, easing: (t) => t * t } }
+ * ```
+ *
+ * 注册的**不覆盖内置**（内置是引擎契约的一部分，被偷偷替换会让同一份文档在不同应用里表现不同）；
+ * 重名注册会明确抛错（`ICE_ANIM_EASING_NAME_CONFLICT`）。
+ */
+import { EasingProgress } from './Easing';
+/**
+ * 注册一个自定义缓动。
+ *
+ * @param name 缓动名（非空字符串；不能与**内置**缓动重名，也不能重复注册同一个名字）
+ * @param fn   归一化进度函数 `(t) => number`
+ */
+export declare function registerEasing(name: string, fn: EasingProgress): void;
+/** 注销自定义缓动（内置缓动不可注销）；返回是否真的移除了。 */
+export declare function unregisterEasing(name: string): boolean;
+/**
+ * 解析缓动：**函数**原样返回（临时自定义）、字符串查内置 → 自定义；没有就返回 null
+ * （调用方决定是回退 linear 还是报错）。
+ */
+export declare function resolveEasing(nameOrFn: any): EasingProgress | null;
+/** 当前可用的缓动名（内置 + 自定义），用于校验提示与文档。 */
+export declare function easingNames(): string[];
+/** 只列出应用层注册的缓动名（调试 / 测试用）。 */
+export declare function customEasingNames(): string[];

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

@@ -0,0 +1,34 @@
+/**
+ * 可插值取值的**唯一判定与求值入口**：数值 / 等长数字数组 / **颜色** / 带单位数字串。
+ *
+ * 为什么要有颜色：`fillStyle` 从红渐变到蓝是界面里最常见的动效之一，而 canvas 只会画字符串。
+ * 早先引擎一律拒绝非数值取值（避免写出 NaN 破坏矩阵），代价就是"颜色动画做不了"。
+ * 这里把"哪些类型可插值、怎么插值"收敛到一个模块：校验器（`validateAnimations`）与
+ * 运行时（`AnimationManager`）都用它，避免"校验通过但跑起来算错"。
+ *
+ * 支持的类型：
+ * - `number`：线性插值；
+ * - `number[]`（等长）：逐元素线性插值（矩阵/位移/缩放都走这条）；
+ * - 颜色字符串：`#rgb` / `#rgba` / `#rrggbb` / `#rrggbbaa` / `rgb()` / `rgba()`（两端必须都是颜色）；
+ * - 带单位数字串：`'12px'` / `'1.5em'` 等（**单位必须一致**，否则视为不可插值）。
+ *
+ * 注意：插值在 **sRGB 数值空间**做（与 CSS `transition` 的默认行为一致），不做 OKLab 之类感知均匀空间。
+ */
+export type AnimationValueKind = 'number' | 'array' | 'color' | 'length' | null;
+/** 解析颜色字符串为 `[r, g, b, a]`（a ∈ [0,1]）；不是颜色返回 null。 */
+export declare function parseColor(value: any): [number, number, number, number] | null;
+/** 把 `[r,g,b,a]` 写回 `rgba(...)`（alpha 为 1 时给 `rgb(...)`，与输入形态无关，输出统一）。 */
+export declare function formatColor(rgba: [number, number, number, number]): string;
+/** 解析带单位数字串（`'12px'` / `'1.5em'`）→ `{ number, unit }`；不是就返回 null。 */
+export declare function parseNumberWithUnit(value: any): {
+    number: number;
+    unit: string;
+} | null;
+/** 取值种类（`null` = 不可插值）。 */
+export declare function classifyValue(value: any): AnimationValueKind;
+/** 两个取值能否互相插值（同型；数组等长；带单位数字串单位一致）。 */
+export declare function isInterpolatable(from: any, to: any): boolean;
+/**
+ * 按进度 `p` 求值。不可插值时返回 `from`（调用方负责在校验阶段拦住非法配置）。
+ */
+export declare function interpolateValue(from: any, to: any, p: number): any;

package/dist/types/animation/interpolators.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 可插值取值的**唯一判定与求值入口**：数值 / 等长数字数组 / **颜色** / 带单位数字串。
+ *
+ * 为什么要有颜色：`fillStyle` 从红渐变到蓝是界面里最常见的动效之一，而 canvas 只会画字符串。
+ * 早先引擎一律拒绝非数值取值（避免写出 NaN 破坏矩阵），代价就是"颜色动画做不了"。
+ * 这里把"哪些类型可插值、怎么插值"收敛到一个模块：校验器（`validateAnimations`）与
+ * 运行时（`AnimationManager`）都用它，避免"校验通过但跑起来算错"。
+ *
+ * 支持的类型：
+ * - `number`：线性插值；
+ * - `number[]`（等长）：逐元素线性插值（矩阵/位移/缩放都走这条）；
+ * - 颜色字符串：`#rgb` / `#rgba` / `#rrggbb` / `#rrggbbaa` / `rgb()` / `rgba()`（两端必须都是颜色）；
+ * - 带单位数字串：`'12px'` / `'1.5em'` 等（**单位必须一致**，否则视为不可插值）。
+ *
+ * 注意：插值在 **sRGB 数值空间**做（与 CSS `transition` 的默认行为一致），不做 OKLab 之类感知均匀空间。
+ */
+export type AnimationValueKind = 'number' | 'array' | 'color' | 'length' | null;
+/** 解析颜色字符串为 `[r, g, b, a]`（a ∈ [0,1]）；不是颜色返回 null。 */
+export declare function parseColor(value: any): [number, number, number, number] | null;
+/** 把 `[r,g,b,a]` 写回 `rgba(...)`（alpha 为 1 时给 `rgb(...)`，与输入形态无关，输出统一）。 */
+export declare function formatColor(rgba: [number, number, number, number]): string;
+/** 解析带单位数字串（`'12px'` / `'1.5em'`）→ `{ number, unit }`；不是就返回 null。 */
+export declare function parseNumberWithUnit(value: any): {
+    number: number;
+    unit: string;
+} | null;
+/** 取值种类（`null` = 不可插值）。 */
+export declare function classifyValue(value: any): AnimationValueKind;
+/** 两个取值能否互相插值（同型；数组等长；带单位数字串单位一致）。 */
+export declare function isInterpolatable(from: any, to: any): boolean;
+/**
+ * 按进度 `p` 求值。不可插值时返回 `from`（调用方负责在校验阶段拦住非法配置）。
+ */
+export declare function interpolateValue(from: any, to: any, p: number): any;

package/dist/types/animation/validate-animations.d.mts

@@ -0,0 +1,55 @@
+import { AnimationValueKind } from './interpolators.mjs';
+export declare const ICE_ANIMATION_DIAGNOSTIC_CODES: {
+    /** 键不是合法的属性路径（空串 / 非字符串）。 */
+    readonly KEY_INVALID: "ICE_ANIM_KEY_INVALID";
+    /** `duration` 缺失 / 非正数 / 超上限 / 不是已注册的 motion token。 */
+    readonly DURATION_INVALID: "ICE_ANIM_DURATION_INVALID";
+    /** `delay` 不是非负有限数。 */
+    readonly DELAY_INVALID: "ICE_ANIM_DELAY_INVALID";
+    /** `iterationCount` 不是 ≥1 的整数。 */
+    readonly ITERATION_INVALID: "ICE_ANIM_ITERATION_INVALID";
+    /** 缓动名既不是内置缓动，也不是主题 motion.easing 里的语义名（运行时会回退 linear）。 */
+    readonly EASING_UNKNOWN: "ICE_ANIM_EASING_UNKNOWN";
+    /** `from` / `to` 不是可插值的同型数值（数值或等长数字数组）。 */
+    readonly VALUE_NOT_INTERPOLATABLE: "ICE_ANIM_VALUE_NOT_INTERPOLATABLE";
+    /** `keyframes` 形状非法（少于 2 帧 / offset 非有限数 / 各帧取值不同型或不等长）。 */
+    readonly KEYFRAMES_INVALID: "ICE_ANIM_KEYFRAMES_INVALID";
+    /** 无限循环（`loop: true`）：Agent 生成的界面里要谨慎，建议给 `iterationCount` 或可中断入口。 */
+    readonly INFINITE_LOOP: "ICE_ANIM_INFINITE_LOOP";
+    /** 该属性会改变派生参数（尺寸 / 点集 / 文本量测）→ 每帧都要重量测，性能上不划算。 */
+    readonly KEY_AFFECTS_MEASUREMENT: "ICE_ANIM_KEY_AFFECTS_MEASUREMENT";
+    /** 运行期告知：用户开启了「减少动态效果」，这条动画被折叠成终态（未播放过程）。 */
+    readonly REDUCED_MOTION: "ICE_ANIM_REDUCED_MOTION";
+    /** `direction` 不是 `normal` / `reverse` / `alternate`。 */
+    readonly DIRECTION_INVALID: "ICE_ANIM_DIRECTION_INVALID";
+    /** 生命周期回调（onStart/onUpdate/onRepeat/onComplete）抛了异常（已忽略，不打断动画）。 */
+    readonly CALLBACK_ERROR: "ICE_ANIM_CALLBACK_ERROR";
+};
+export type ICEAnimationDiagnosticCode = (typeof ICE_ANIMATION_DIAGNOSTIC_CODES)[keyof typeof ICE_ANIMATION_DIAGNOSTIC_CODES];
+export interface ICEAnimationDiagnostic {
+    severity: 'error' | 'warning';
+    code: ICEAnimationDiagnosticCode;
+    message: string;
+    /** 出问题的位置：属性动画键（如 `transform.translate`），便于 Agent 精确改一处。 */
+    path: string;
+}
+export type ValidateAnimationsOptions = {
+    /** 主题 motion token（缺省用内置默认主题）——`duration: 'normal'` / `easing: 'out'` 这类语义名靠它解析。 */
+    motionTokens?: {
+        duration?: Record<string, any>;
+        easing?: Record<string, any>;
+    } | null;
+    /** 判断某个属性键是否"动画安全"（不影响派生参数）；给了就会对不安全的键出性能警告。 */
+    isSafeKey?: ((path: string) => boolean) | null;
+    /** 单条动画的时长上限（ms），默认 60s；Agent 生成的长动画多半是写错了。 */
+    maxDuration?: number;
+};
+/**
+ * 取值种类：`number` / `array`（等长数字数组）/ `color` / `length`（带单位数字串）/ `null`（不可插值）。
+ * 判定与求值都转发到 `interpolators.ts`（运行时同源，避免"校验通过但跑起来算错"）。
+ */
+export declare function classifyAnimationValue(value: any): AnimationValueKind;
+/** 两个取值能否互相插值（同型；数组等长；颜色互插；带单位数字串单位一致）。 */
+export declare function isInterpolatablePair(from: any, to: any): boolean;
+/** 校验一份 `animations` 配置（键 → 单段/关键帧配置），返回按 `path` 排序的诊断列表（无问题 = 空数组）。 */
+export declare function validateAnimations(animations: any, options?: ValidateAnimationsOptions): ICEAnimationDiagnostic[];

package/dist/types/animation/validate-animations.d.ts

@@ -0,0 +1,55 @@
+import { AnimationValueKind } from './interpolators';
+export declare const ICE_ANIMATION_DIAGNOSTIC_CODES: {
+    /** 键不是合法的属性路径（空串 / 非字符串）。 */
+    readonly KEY_INVALID: "ICE_ANIM_KEY_INVALID";
+    /** `duration` 缺失 / 非正数 / 超上限 / 不是已注册的 motion token。 */
+    readonly DURATION_INVALID: "ICE_ANIM_DURATION_INVALID";
+    /** `delay` 不是非负有限数。 */
+    readonly DELAY_INVALID: "ICE_ANIM_DELAY_INVALID";
+    /** `iterationCount` 不是 ≥1 的整数。 */
+    readonly ITERATION_INVALID: "ICE_ANIM_ITERATION_INVALID";
+    /** 缓动名既不是内置缓动，也不是主题 motion.easing 里的语义名（运行时会回退 linear）。 */
+    readonly EASING_UNKNOWN: "ICE_ANIM_EASING_UNKNOWN";
+    /** `from` / `to` 不是可插值的同型数值（数值或等长数字数组）。 */
+    readonly VALUE_NOT_INTERPOLATABLE: "ICE_ANIM_VALUE_NOT_INTERPOLATABLE";
+    /** `keyframes` 形状非法（少于 2 帧 / offset 非有限数 / 各帧取值不同型或不等长）。 */
+    readonly KEYFRAMES_INVALID: "ICE_ANIM_KEYFRAMES_INVALID";
+    /** 无限循环（`loop: true`）：Agent 生成的界面里要谨慎，建议给 `iterationCount` 或可中断入口。 */
+    readonly INFINITE_LOOP: "ICE_ANIM_INFINITE_LOOP";
+    /** 该属性会改变派生参数（尺寸 / 点集 / 文本量测）→ 每帧都要重量测，性能上不划算。 */
+    readonly KEY_AFFECTS_MEASUREMENT: "ICE_ANIM_KEY_AFFECTS_MEASUREMENT";
+    /** 运行期告知：用户开启了「减少动态效果」，这条动画被折叠成终态（未播放过程）。 */
+    readonly REDUCED_MOTION: "ICE_ANIM_REDUCED_MOTION";
+    /** `direction` 不是 `normal` / `reverse` / `alternate`。 */
+    readonly DIRECTION_INVALID: "ICE_ANIM_DIRECTION_INVALID";
+    /** 生命周期回调（onStart/onUpdate/onRepeat/onComplete）抛了异常（已忽略，不打断动画）。 */
+    readonly CALLBACK_ERROR: "ICE_ANIM_CALLBACK_ERROR";
+};
+export type ICEAnimationDiagnosticCode = (typeof ICE_ANIMATION_DIAGNOSTIC_CODES)[keyof typeof ICE_ANIMATION_DIAGNOSTIC_CODES];
+export interface ICEAnimationDiagnostic {
+    severity: 'error' | 'warning';
+    code: ICEAnimationDiagnosticCode;
+    message: string;
+    /** 出问题的位置：属性动画键（如 `transform.translate`），便于 Agent 精确改一处。 */
+    path: string;
+}
+export type ValidateAnimationsOptions = {
+    /** 主题 motion token（缺省用内置默认主题）——`duration: 'normal'` / `easing: 'out'` 这类语义名靠它解析。 */
+    motionTokens?: {
+        duration?: Record<string, any>;
+        easing?: Record<string, any>;
+    } | null;
+    /** 判断某个属性键是否"动画安全"（不影响派生参数）；给了就会对不安全的键出性能警告。 */
+    isSafeKey?: ((path: string) => boolean) | null;
+    /** 单条动画的时长上限（ms），默认 60s；Agent 生成的长动画多半是写错了。 */
+    maxDuration?: number;
+};
+/**
+ * 取值种类：`number` / `array`（等长数字数组）/ `color` / `length`（带单位数字串）/ `null`（不可插值）。
+ * 判定与求值都转发到 `interpolators.ts`（运行时同源，避免"校验通过但跑起来算错"）。
+ */
+export declare function classifyAnimationValue(value: any): AnimationValueKind;
+/** 两个取值能否互相插值（同型；数组等长；颜色互插；带单位数字串单位一致）。 */
+export declare function isInterpolatablePair(from: any, to: any): boolean;
+/** 校验一份 `animations` 配置（键 → 单段/关键帧配置），返回按 `path` 排序的诊断列表（无问题 = 空数组）。 */
+export declare function validateAnimations(animations: any, options?: ValidateAnimationsOptions): ICEAnimationDiagnostic[];

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

@@ -58,6 +58,14 @@ declare class DOMEventDispatcher {
      * 相对每帧渲染可忽略（见 AGENTS「性能相关铁律」）。
      */
     private __resolveCanvasRect;
+    /**
+     * 事件目标是否属于「别的 canvas」（同页另一个 ICE 实例的绘制面）。
+     *
+     * - 目标是本实例的 canvas、或本实例 canvas 内的元素 → 不是"外来"事件；
+     * - 目标不是 canvas（body / window / 工具栏按钮等）→ 不是"外来"事件（键盘、合成事件照旧）；
+     * - 目标正是**另一个 canvas 元素** → 外来事件，本实例应忽略。
+     */
+    private __isForeignCanvasTarget;
     set stopped(flag: boolean);
     get stopped(): boolean;
     /**

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

@@ -58,6 +58,14 @@ declare class DOMEventDispatcher {
      * 相对每帧渲染可忽略（见 AGENTS「性能相关铁律」）。
      */
     private __resolveCanvasRect;
+    /**
+     * 事件目标是否属于「别的 canvas」（同页另一个 ICE 实例的绘制面）。
+     *
+     * - 目标是本实例的 canvas、或本实例 canvas 内的元素 → 不是"外来"事件；
+     * - 目标不是 canvas（body / window / 工具栏按钮等）→ 不是"外来"事件（键盘、合成事件照旧）；
+     * - 目标正是**另一个 canvas 元素** → 外来事件，本实例应忽略。
+     */
+    private __isForeignCanvasTarget;
     set stopped(flag: boolean);
     get stopped(): boolean;
     /**

package/dist/types/export/SvgExporter.d.mts

@@ -50,5 +50,12 @@ export type SvgExportResult = {
  *
  * @param target ICE 实例（导出整幅画布）或任意组件（导出它的子树）
  */
-export declare function exportSvg(target: any, options?: SvgExportOptions): string;
-export declare function exportSvgResult(target: any, options?: SvgExportOptions): SvgExportResult;
+/**
+ * 导出场景为 SVG 字符串。
+ *
+ * `target` 可以是 **ICE 实例**、**任意组件**，也可以是**这两个的数组**（多层合成）：
+ * 分层渲染（静态层 + 动画层）导出时按数组顺序叠加，各层的世界坐标共用同一套 `worldToView`。
+ * 单层（传单个 target）的输出与历史版本逐字节一致。
+ */
+export declare function exportSvg(target: any | any[], options?: SvgExportOptions): string;
+export declare function exportSvgResult(target: any | any[], options?: SvgExportOptions): SvgExportResult;