ice-render 1.0.4 → 1.0.5

package/dist/types/renderer/CanvasRenderer.d.mts

@@ -0,0 +1,150 @@
+import ICEEventTarget from '../event/ICEEventTarget.mjs';
+import ICE from '../ICE.mjs';
+/**
+ * @class CanvasRenderer Canvas 渲染器
+ *
+ * - 一个 ICE 实例上，只能有一个渲染器实例。
+ * - 默认渲染策略为「脏矩形局部重绘」（renderMode: 'dirty-rect'）：
+ *   只 clear 脏区域、按 z 序重画与区域相交的组件；不满足局部条件时自动回退全量重绘
+ *   （结构变更 / 未 prime / 脏占比过高 / 区域过大 / 折线或文本等特殊类别 / 能力缺失）。
+ *   两种模式像素一致（组件 render 已做 ctx 泄漏属性归位，见 ICEComponent.__resetLeakyCtxState）。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class CanvasRenderer extends ICEEventTarget {
+    private ice;
+    private stopped;
+    private renderMode;
+    /** @internal 内部测试钩子：强制走全量路径（对比/调试用，非公开 API）。 */
+    __forceFullRender: boolean;
+    private componentQueue;
+    private toolsQueue;
+    private __queueDirty;
+    private __zSnap;
+    /**
+     * 每个「曾上屏」组件的世界轴对齐包围盒快照（[minX,minY,maxX,maxY]，已含 paint pad）。
+     * WeakMap：不污染组件 state/props（序列化安全）、对 zIndex 重排免疫、组件 GC 自动回收。
+     * 用于：部分重绘帧的旧区域擦除 + 未变组件的「是否与本帧区域相交」判断。
+     */
+    private __snap;
+    /** 距离最近一次队列重建后，是否已完成过至少一次「全量/prime」渲染（快照就绪）。 */
+    private __primed;
+    /** 组件级离屏缓存（v1 缓存 ICEText），与快照一样不污染组件 state/props。 */
+    private cache;
+    /** @internal 上一帧被视口裁剪掉的组件数（仅供性能观测与测试断言）。 */
+    __lastFrameCulled: number;
+    constructor(ice: ICE, options?: {
+        renderMode?: 'full' | 'dirty-rect';
+    });
+    /**
+     * @method markQueueDirty 标记组件树结构已变化，下一次渲染需重建渲染队列。
+     * 由 ICE / ICEGroup 在 addChild / removeChild 等结构性变更时调用。
+     * 结构变更必然回退全量重绘（并重新 prime 快照）。
+     */
+    markQueueDirty(): void;
+    setRenderMode(mode: 'full' | 'dirty-rect'): void;
+    getRenderMode(): 'full' | 'dirty-rect';
+    start(): this;
+    stop(): this;
+    private frameEvtHandler;
+    private refreshQueue;
+    private __rebuildQueue;
+    /**
+     * 把当前 componentQueue + toolsQueue 的 zIndex 顺序快照到复用的 __zSnap 数组，
+     * 供下一帧做稳定性比对，避免每帧分配新数组。
+     */
+    private __snapshotZ;
+    /**
+     * 对比当前队列的 zIndex 与上次快照，任一不同（或长度变化）即认为顺序已变。
+     */
+    private __zOrderChanged;
+    private doRenderFull;
+    /**
+     * 收集脏区域并做局部重绘可行性判定。
+     * 返回 null = 不满足局部条件（由调用方回退全量）；否则返回本帧脏区域 [minX,minY,maxX,maxY]。
+     *
+     * 区域来源：
+     * - 可见且 dirty 的组件/工具：旧快照盒 ∪ 新几何盒（可能移动/变形）。
+     * - display:false 且 dirty 且曾上屏的组件/工具：旧快照盒（仅擦除）。
+     *
+     * 判定顺序（性能关键）：先做**零开销预检**（只读 display/dirty 标志），
+     * 能确定要回退全量的情况（无可见脏组件 / 脏占比超阈）绝不进入
+     * 「场景门控 + 逐组件算包围盒」的昂贵路径——否则动画全量帧会被重复 compose 翻倍。
+     */
+    private __collect;
+    /** 渲染视口（dpr·viewport）。ICE 侧有缓存，dpr===1 时直接返回 viewport 本身。 */
+    private __renderViewport;
+    /**
+     * 预检：只读组件标志（display/dirty/快照存在），不触发矩阵/样式计算。
+     * @returns { visible: 可见数量, dirty: 可见且脏数量, hiddenErase: 是否有曾上屏的隐藏脏组件 }
+     */
+    private __preCount;
+    /**
+     * 区域收集 pass：仅当预检通过、即将走局部时才调用。
+     * 把「可见且脏」组件的旧快照盒 ∪ 新几何盒、以及「隐藏且曾上屏」组件的旧快照盒
+     * 逐条推进 `boxes`（聚合交给 `coalesceRegions`，这里不做并集）。
+     * 返回 false = 有组件盒非法（回退全量）。
+     */
+    private __collectDirtyBoxes;
+    /**
+     * 相交级门控：判断「对本帧脏区域有 AA 风险的组件」是否真的与区域相交。
+     *
+     * 有风险的类别（与整场景门控时代一致）：
+     * - 点集路径（星形/正N边形/玫瑰/折线）：clip 会切断折线抗锯齿边缘
+     * - 文本：clip 会改变字形 AA
+     * - 非不透明落墨（rgba/hsla 色、阴影、globalAlpha≠1、非 source-over）
+     *
+     * 例外：已离屏缓存的组件在主画布上只是 drawImage（不透明位图整像素采样），
+     * 不再受 clip 影响，因此不阻塞。
+     *
+     * **刚变脏的 risky 组件一律回退**：它本轮要重建位图/重算参数，而实际墨迹范围可能超出
+     * 几何盒（文本的字形与描边尤甚，实测「文本内容变更」时墨迹会超出盒若干像素），
+     * 在 clip 下重绘无法保证与全量逐像素一致。dirty-rect 像素回归正是靠这条兜住的。
+     *
+     * 干净的 risky 组件才做相交判定，盒取上屏快照（世界轴对齐盒，含 paint pad）；
+     * 快照缺失（从未上屏）时无法判定 → 保守回退。
+     */
+    private __riskyIntersectsRegions;
+    private __renderDirtyRect;
+    /**
+     * 调用插件渲染钩子。要求：
+     * - 与世界坐标一致：先把 CTM 设为「渲染视口」（dpr · viewport），插件即可按世界坐标绘制
+     * - 在两条渲染路径中都调用；局部重绘时处于 clip 之内，语义与组件一致
+     * - 未注册任何钩子时零开销（不构造 frame 对象）
+     */
+    private __invokePluginRender;
+    private __ensureContext;
+    /**
+     * @internal 取组件上一次上屏的世界包围盒（含 paint pad，格式 [minX,minY,maxX,maxY]）。
+     * 供命中检测做「廉价包围盒预筛」，避免对屏外组件做矩阵反变换 + 形状判定。无快照返回 null。
+     */
+    getWorldBox(component: any): Float64Array | null;
+    /**
+     * 当前视口对应的可见世界矩形 [minX,minY,maxX,maxY]。画布尺寸缺失时返回 null（不裁剪）。
+     */
+    private __visibleWorldRect;
+    /**
+     * 组件渲染入口：可缓存组件走离屏位图（命中贴图 / 纯平移复用 / 重建），
+     * 否则回退到普通 render()。
+     */
+    private __renderComponent;
+    private __isDotPath;
+    private __isText;
+    /**
+     * 计算 dirty 组件的「新盒」（含 paint pad，世界坐标）。
+     * 需要先刷新组件参数（文本 measure / dot-path calcDots），再 refresh 合成矩阵。
+     * 返回 null = 盒非法或计算失败（回退全量）。
+     */
+    private __freshBox;
+    /**
+     * 渲染后捕获组件的世界包围盒（含 pad）到快照，供后续帧做旧区域擦除与相交判断。
+     */
+    private __capture;
+    /**
+     * 隐藏组件（display:false）曾上屏过、且仍挂着脏标记（render 提前返回不会自清）：
+     * 本帧它的旧区域已被擦除（全量 clear 或局部 erase 区域），因此清除脏位并移除快照，
+     * 避免「永久脏组件把后续局部帧反复顶成全量」。display 重新打开时 setState 会重新置脏。
+     */
+    private __finalizeHidden;
+}
+export default CanvasRenderer;

package/dist/types/renderer/CanvasRenderer.d.ts

@@ -1,22 +1,150 @@
-import ICEEventTarget from '../event/ICEEventTarget';
-import ICE from '../ICE';
-/**
- * @class CanvasRenderer Canvas 渲染器
- *
- * - 一个 ICE 实例上，只能有一个渲染器实例。
- *
- * @author 大漠穷秋<damoqiongqiu@126.com>
- */
-declare class CanvasRenderer extends ICEEventTarget {
-    private ice;
-    private stopped;
-    private componentQueue;
-    private toolsQueue;
-    constructor(ice: ICE);
-    start(): this;
-    stop(): this;
-    private frameEvtHandler;
-    private refreshQueue;
-    private doRender;
-}
-export default CanvasRenderer;
+import ICEEventTarget from '../event/ICEEventTarget';
+import ICE from '../ICE';
+/**
+ * @class CanvasRenderer Canvas 渲染器
+ *
+ * - 一个 ICE 实例上，只能有一个渲染器实例。
+ * - 默认渲染策略为「脏矩形局部重绘」（renderMode: 'dirty-rect'）：
+ *   只 clear 脏区域、按 z 序重画与区域相交的组件；不满足局部条件时自动回退全量重绘
+ *   （结构变更 / 未 prime / 脏占比过高 / 区域过大 / 折线或文本等特殊类别 / 能力缺失）。
+ *   两种模式像素一致（组件 render 已做 ctx 泄漏属性归位，见 ICEComponent.__resetLeakyCtxState）。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class CanvasRenderer extends ICEEventTarget {
+    private ice;
+    private stopped;
+    private renderMode;
+    /** @internal 内部测试钩子：强制走全量路径（对比/调试用，非公开 API）。 */
+    __forceFullRender: boolean;
+    private componentQueue;
+    private toolsQueue;
+    private __queueDirty;
+    private __zSnap;
+    /**
+     * 每个「曾上屏」组件的世界轴对齐包围盒快照（[minX,minY,maxX,maxY]，已含 paint pad）。
+     * WeakMap：不污染组件 state/props（序列化安全）、对 zIndex 重排免疫、组件 GC 自动回收。
+     * 用于：部分重绘帧的旧区域擦除 + 未变组件的「是否与本帧区域相交」判断。
+     */
+    private __snap;
+    /** 距离最近一次队列重建后，是否已完成过至少一次「全量/prime」渲染（快照就绪）。 */
+    private __primed;
+    /** 组件级离屏缓存（v1 缓存 ICEText），与快照一样不污染组件 state/props。 */
+    private cache;
+    /** @internal 上一帧被视口裁剪掉的组件数（仅供性能观测与测试断言）。 */
+    __lastFrameCulled: number;
+    constructor(ice: ICE, options?: {
+        renderMode?: 'full' | 'dirty-rect';
+    });
+    /**
+     * @method markQueueDirty 标记组件树结构已变化，下一次渲染需重建渲染队列。
+     * 由 ICE / ICEGroup 在 addChild / removeChild 等结构性变更时调用。
+     * 结构变更必然回退全量重绘（并重新 prime 快照）。
+     */
+    markQueueDirty(): void;
+    setRenderMode(mode: 'full' | 'dirty-rect'): void;
+    getRenderMode(): 'full' | 'dirty-rect';
+    start(): this;
+    stop(): this;
+    private frameEvtHandler;
+    private refreshQueue;
+    private __rebuildQueue;
+    /**
+     * 把当前 componentQueue + toolsQueue 的 zIndex 顺序快照到复用的 __zSnap 数组，
+     * 供下一帧做稳定性比对，避免每帧分配新数组。
+     */
+    private __snapshotZ;
+    /**
+     * 对比当前队列的 zIndex 与上次快照，任一不同（或长度变化）即认为顺序已变。
+     */
+    private __zOrderChanged;
+    private doRenderFull;
+    /**
+     * 收集脏区域并做局部重绘可行性判定。
+     * 返回 null = 不满足局部条件（由调用方回退全量）；否则返回本帧脏区域 [minX,minY,maxX,maxY]。
+     *
+     * 区域来源：
+     * - 可见且 dirty 的组件/工具：旧快照盒 ∪ 新几何盒（可能移动/变形）。
+     * - display:false 且 dirty 且曾上屏的组件/工具：旧快照盒（仅擦除）。
+     *
+     * 判定顺序（性能关键）：先做**零开销预检**（只读 display/dirty 标志），
+     * 能确定要回退全量的情况（无可见脏组件 / 脏占比超阈）绝不进入
+     * 「场景门控 + 逐组件算包围盒」的昂贵路径——否则动画全量帧会被重复 compose 翻倍。
+     */
+    private __collect;
+    /** 渲染视口（dpr·viewport）。ICE 侧有缓存，dpr===1 时直接返回 viewport 本身。 */
+    private __renderViewport;
+    /**
+     * 预检：只读组件标志（display/dirty/快照存在），不触发矩阵/样式计算。
+     * @returns { visible: 可见数量, dirty: 可见且脏数量, hiddenErase: 是否有曾上屏的隐藏脏组件 }
+     */
+    private __preCount;
+    /**
+     * 区域收集 pass：仅当预检通过、即将走局部时才调用。
+     * 把「可见且脏」组件的旧快照盒 ∪ 新几何盒、以及「隐藏且曾上屏」组件的旧快照盒
+     * 逐条推进 `boxes`（聚合交给 `coalesceRegions`，这里不做并集）。
+     * 返回 false = 有组件盒非法（回退全量）。
+     */
+    private __collectDirtyBoxes;
+    /**
+     * 相交级门控：判断「对本帧脏区域有 AA 风险的组件」是否真的与区域相交。
+     *
+     * 有风险的类别（与整场景门控时代一致）：
+     * - 点集路径（星形/正N边形/玫瑰/折线）：clip 会切断折线抗锯齿边缘
+     * - 文本：clip 会改变字形 AA
+     * - 非不透明落墨（rgba/hsla 色、阴影、globalAlpha≠1、非 source-over）
+     *
+     * 例外：已离屏缓存的组件在主画布上只是 drawImage（不透明位图整像素采样），
+     * 不再受 clip 影响，因此不阻塞。
+     *
+     * **刚变脏的 risky 组件一律回退**：它本轮要重建位图/重算参数，而实际墨迹范围可能超出
+     * 几何盒（文本的字形与描边尤甚，实测「文本内容变更」时墨迹会超出盒若干像素），
+     * 在 clip 下重绘无法保证与全量逐像素一致。dirty-rect 像素回归正是靠这条兜住的。
+     *
+     * 干净的 risky 组件才做相交判定，盒取上屏快照（世界轴对齐盒，含 paint pad）；
+     * 快照缺失（从未上屏）时无法判定 → 保守回退。
+     */
+    private __riskyIntersectsRegions;
+    private __renderDirtyRect;
+    /**
+     * 调用插件渲染钩子。要求：
+     * - 与世界坐标一致：先把 CTM 设为「渲染视口」（dpr · viewport），插件即可按世界坐标绘制
+     * - 在两条渲染路径中都调用；局部重绘时处于 clip 之内，语义与组件一致
+     * - 未注册任何钩子时零开销（不构造 frame 对象）
+     */
+    private __invokePluginRender;
+    private __ensureContext;
+    /**
+     * @internal 取组件上一次上屏的世界包围盒（含 paint pad，格式 [minX,minY,maxX,maxY]）。
+     * 供命中检测做「廉价包围盒预筛」，避免对屏外组件做矩阵反变换 + 形状判定。无快照返回 null。
+     */
+    getWorldBox(component: any): Float64Array | null;
+    /**
+     * 当前视口对应的可见世界矩形 [minX,minY,maxX,maxY]。画布尺寸缺失时返回 null（不裁剪）。
+     */
+    private __visibleWorldRect;
+    /**
+     * 组件渲染入口：可缓存组件走离屏位图（命中贴图 / 纯平移复用 / 重建），
+     * 否则回退到普通 render()。
+     */
+    private __renderComponent;
+    private __isDotPath;
+    private __isText;
+    /**
+     * 计算 dirty 组件的「新盒」（含 paint pad，世界坐标）。
+     * 需要先刷新组件参数（文本 measure / dot-path calcDots），再 refresh 合成矩阵。
+     * 返回 null = 盒非法或计算失败（回退全量）。
+     */
+    private __freshBox;
+    /**
+     * 渲染后捕获组件的世界包围盒（含 pad）到快照，供后续帧做旧区域擦除与相交判断。
+     */
+    private __capture;
+    /**
+     * 隐藏组件（display:false）曾上屏过、且仍挂着脏标记（render 提前返回不会自清）：
+     * 本帧它的旧区域已被擦除（全量 clear 或局部 erase 区域），因此清除脏位并移除快照，
+     * 避免「永久脏组件把后续局部帧反复顶成全量」。display 重新打开时 setState 会重新置脏。
+     */
+    private __finalizeHidden;
+}
+export default CanvasRenderer;

package/dist/types/renderer/ObjectCache.d.mts

@@ -0,0 +1,79 @@
+export interface CachedSurface {
+    canvas: any;
+    ctx: any;
+    /** 位图尺寸（设备像素，四周各含 1px 透明余量，用于吸收贴图取整误差）。 */
+    pw: number;
+    ph: number;
+    /** 当前贴图落点（整数设备像素）。 */
+    dx: number;
+    dy: number;
+    /** 建位图时的贴图落点；纯平移复用由 `dx0/dy0` 加「设备像素取整的位移」推出，不会累积漂移。 */
+    dx0: number;
+    dy0: number;
+    /** 建位图时的世界盒左上角（paint pad 之后）。 */
+    buildMinX: number;
+    buildMinY: number;
+    /** 建位图时的渲染视口：`device = world * rs + (ox, oy)`。视口一变，位图即失效。 */
+    rs: number;
+    ox: number;
+    oy: number;
+    contentKey: string;
+    linearKey: string;
+}
+declare class ObjectCache {
+    private ice;
+    private map;
+    /** 已缓存位图的累计字节数（用于总预算门控；WeakMap 不可遍历，故显式记账）。 */
+    private __bytes;
+    /** 上一帧的渲染视口（复用同一对象，避免每帧分配）。 */
+    private __vp;
+    /** 本帧的渲染视口是否与上一帧不同。视口变化帧一律不缓存，见 `beginFrame()`。 */
+    private __vpChanged;
+    constructor(ice: any);
+    /** 渲染视口：世界 → 画布设备像素的仿射映射（`device = world * scale + (tx, ty)`）。 */
+    private __rvp;
+    /**
+     * 渲染器每帧开头调用：记录「渲染视口是否相对上一帧发生了变化」。
+     *
+     * 视口一变，所有位图的栅格都要重算（重新光栅化），代价与「这一帧直接落墨」同阶；
+     * 而缩放/平移过程中视口每帧都在变 —— 那时缓存只会白扫一遍整屏。因此视口变化的那一帧
+     * 直接停用缓存（`isCachable` 返回 false），落到与旧引擎一致的直接绘制路径；
+     * 手势停下后的第一帧再统一重建一次。
+     */
+    beginFrame(): void;
+    /** 位图是否与当前渲染视口同源（缩放与平移都必须一致，否则栅格不再对齐）。 */
+    private __sameViewport;
+    /**
+     * 组件是否走离屏缓存。v1 只缓存「非编辑态、可见」的 ICEText；后续可扩展到 dot-path /
+     * 半透明 / ICEGroup 子树。
+     */
+    isCachable(component: any): boolean;
+    has(component: any): boolean;
+    /**
+     * 内容指纹：决定位图是否需要重新光栅化。只涵盖影响文本外观的 state 字段，
+     * 不包含 left/top/transform（由 linearKey 单独处理，以便纯平移复用）。
+     */
+    contentKey(component: any): string;
+    private __styleKey;
+    /** 线性变换指纹（composedMatrix 的 a,b,c,d）；平移分量单独保存，供纯平移复用。 */
+    linearKey(component: any): string;
+    /**
+     * 按缓存路径渲染组件。
+     * @returns true = 已由缓存处理；false = 组件不可缓存，调用方应回退到 component.render()。
+     */
+    render(component: any): boolean;
+    /** 组件的「真实落墨盒」（世界坐标）：几何盒 + paint pad。 */
+    private __paintBox;
+    private build;
+    /**
+     * 纯平移复用：保持位图内容不变，把贴图落点按「设备像素取整的位移」挪过去。
+     *
+     * @returns false = 位图已罩不住新盒（或位移非设备像素对齐）→ 调用方必须重建。
+     */
+    private refreshPosition;
+    /** 贴图：回到单位变换，按整数设备像素落点 1:1 拷贝位图（不传目标宽高 → 零重采样）。 */
+    private draw;
+    invalidate(component: any): void;
+    clear(): void;
+}
+export default ObjectCache;

package/dist/types/renderer/ObjectCache.d.ts

@@ -0,0 +1,79 @@
+export interface CachedSurface {
+    canvas: any;
+    ctx: any;
+    /** 位图尺寸（设备像素，四周各含 1px 透明余量，用于吸收贴图取整误差）。 */
+    pw: number;
+    ph: number;
+    /** 当前贴图落点（整数设备像素）。 */
+    dx: number;
+    dy: number;
+    /** 建位图时的贴图落点；纯平移复用由 `dx0/dy0` 加「设备像素取整的位移」推出，不会累积漂移。 */
+    dx0: number;
+    dy0: number;
+    /** 建位图时的世界盒左上角（paint pad 之后）。 */
+    buildMinX: number;
+    buildMinY: number;
+    /** 建位图时的渲染视口：`device = world * rs + (ox, oy)`。视口一变，位图即失效。 */
+    rs: number;
+    ox: number;
+    oy: number;
+    contentKey: string;
+    linearKey: string;
+}
+declare class ObjectCache {
+    private ice;
+    private map;
+    /** 已缓存位图的累计字节数（用于总预算门控；WeakMap 不可遍历，故显式记账）。 */
+    private __bytes;
+    /** 上一帧的渲染视口（复用同一对象，避免每帧分配）。 */
+    private __vp;
+    /** 本帧的渲染视口是否与上一帧不同。视口变化帧一律不缓存，见 `beginFrame()`。 */
+    private __vpChanged;
+    constructor(ice: any);
+    /** 渲染视口：世界 → 画布设备像素的仿射映射（`device = world * scale + (tx, ty)`）。 */
+    private __rvp;
+    /**
+     * 渲染器每帧开头调用：记录「渲染视口是否相对上一帧发生了变化」。
+     *
+     * 视口一变，所有位图的栅格都要重算（重新光栅化），代价与「这一帧直接落墨」同阶；
+     * 而缩放/平移过程中视口每帧都在变 —— 那时缓存只会白扫一遍整屏。因此视口变化的那一帧
+     * 直接停用缓存（`isCachable` 返回 false），落到与旧引擎一致的直接绘制路径；
+     * 手势停下后的第一帧再统一重建一次。
+     */
+    beginFrame(): void;
+    /** 位图是否与当前渲染视口同源（缩放与平移都必须一致，否则栅格不再对齐）。 */
+    private __sameViewport;
+    /**
+     * 组件是否走离屏缓存。v1 只缓存「非编辑态、可见」的 ICEText；后续可扩展到 dot-path /
+     * 半透明 / ICEGroup 子树。
+     */
+    isCachable(component: any): boolean;
+    has(component: any): boolean;
+    /**
+     * 内容指纹：决定位图是否需要重新光栅化。只涵盖影响文本外观的 state 字段，
+     * 不包含 left/top/transform（由 linearKey 单独处理，以便纯平移复用）。
+     */
+    contentKey(component: any): string;
+    private __styleKey;
+    /** 线性变换指纹（composedMatrix 的 a,b,c,d）；平移分量单独保存，供纯平移复用。 */
+    linearKey(component: any): string;
+    /**
+     * 按缓存路径渲染组件。
+     * @returns true = 已由缓存处理；false = 组件不可缓存，调用方应回退到 component.render()。
+     */
+    render(component: any): boolean;
+    /** 组件的「真实落墨盒」（世界坐标）：几何盒 + paint pad。 */
+    private __paintBox;
+    private build;
+    /**
+     * 纯平移复用：保持位图内容不变，把贴图落点按「设备像素取整的位移」挪过去。
+     *
+     * @returns false = 位图已罩不住新盒（或位移非设备像素对齐）→ 调用方必须重建。
+     */
+    private refreshPosition;
+    /** 贴图：回到单位变换，按整数设备像素落点 1:1 拷贝位图（不传目标宽高 → 零重采样）。 */
+    private draw;
+    invalidate(component: any): void;
+    clear(): void;
+}
+export default ObjectCache;

package/dist/types/renderer/dirty-rect-util.d.mts

@@ -0,0 +1,86 @@
+/**
+ * 脏矩形局部重绘（dirty-rect）的纯函数工具集。
+ *
+ * 本模块不依赖任何引擎实例/ctx，所有几何与阈值计算都可用 jest 直接单测。
+ * 设计目标见 docs/architecture/04-rendering-performance.md「脏矩形局部重绘」章节。
+ *
+ * 盒的表示：一维数组 [minX, minY, maxX, maxY]（世界/画布坐标，轴对齐，已含 paint pad）。
+ */
+/** 抗锯齿兜底余量（px），覆盖 1px 级 AA 溢出与文字 baseline 溢出。 */
+export declare const PAD_AA = 2;
+/**
+ * 命中预筛的包围盒容差（px）。
+ *
+ * 命中的第一道筛子用「渲染快照的世界盒」做 O(1) 拒绝；快照盒本身已含 paint pad
+ * （含 AA 余量），但折线的命中判定自带 errorRange 容差，这里再放宽 1px 作为安全余量，
+ * 确保预筛绝不误杀边界命中。
+ */
+export declare const HIT_BOX_TOLERANCE = 1;
+/**
+ * 计算组件「实际绘制会溢出几何边界多少像素」的保守 padding。
+ * 依据 state（style.lineWidth / lineBorderWidth / shadow 等）实时估算，
+ * 用于把几何包围盒扩成「真实落墨盒」。
+ */
+export declare function stylePaintPad(state: any): number;
+export declare function boxWidth(box: number[]): number;
+export declare function boxHeight(box: number[]): number;
+export declare function boxArea(box: number[]): number;
+/**
+ * 把 src 盒并进 target 盒（原地修改 target，减少分配）。
+ * target 传入空盒（[Infinity,Infinity,-Infinity,-Infinity]）即可从 src 开始累加。
+ */
+export declare function unionBoxes(target: number[], src: number[]): number[];
+/** 判断盒 a 与盒 b 是否相交（含边界相触）。 */
+export declare function intersects(a: number[], b: number[]): boolean;
+/**
+ * 盒内是否有限（无 NaN/Infinity）。非法盒不得参与区域计算或写入快照。
+ */
+export declare function isFiniteBox(box: number[]): boolean;
+/**
+ * 生成一个「空盒」，可用作 unionBoxes 的起点。
+ */
+export declare function emptyBox(): number[];
+/**
+ * 把盒外扩到整像素边界（min 向下取整、max 向上取整），保证 clearRect/clip 用同一像素掩码，
+ * 消除「清除区域与裁剪区域亚像素不一致」导致的接缝。
+ */
+export declare function integerAlign(box: number[]): number[];
+/**
+ * 合并两个盒为一个盒（取并集，不修改入参）。
+ */
+export declare function mergeBox(a: number[], b: number[]): number[];
+export declare function coalesceRegions(boxes: number[][], maxRegions?: number): number[][];
+/**
+ * 多块裁剪区的总面积占画布的比例（用于「接近整屏则回退全量」的判定）。
+ * 各块互不相接，面积可直接相加。
+ */
+export declare function regionsAreaRatio(regions: number[][], canvasWidth: number, canvasHeight: number): number;
+/**
+ * 把「世界坐标盒」映射到「渲染坐标盒」（含 dpr），并向外取整。
+ *
+ * 渲染坐标 = 世界坐标 × 渲染视口 scale + 渲染视口 tx/ty，而 `ICE.getRenderViewport()` 已经
+ * 把 dpr 乘进 scale 与 tx/ty（见 `ICE.getRenderViewport`）。`clearRect` / `clip` 用的正是这个
+ * 坐标系，但脏区收集是在**世界坐标**里做的（上屏快照盒、组件几何盒都是世界盒），
+ * 两者只在「视口为单位变换且 dpr === 1」时才重合 —— 这个函数就是它们之间唯一的换算点。
+ *
+ * 向外取整（min 向下、max 向上）保证映射后的区域不小于真实脏区，避免缩放时边缘出现接缝。
+ */
+export declare function mapBoxToRender(box: number[], viewport: {
+    scale: number;
+    tx: number;
+    ty: number;
+}, out?: number[]): number[];
+/**
+ * 区域占画布总面积的比例，用于「接近整屏则回退全量」的判定。
+ */
+export declare function regionRatio(box: number[], canvasWidth: number, canvasHeight: number): number;
+/**
+ * 判断组件是否以「完全不透明、仅 source-over」的方式绘制。
+ *
+ * dirty-rect 用 clip 把补画限定在脏区域内；clip 边界与「半透明落墨（alpha 色 / 阴影 /
+ * globalAlpha / 合成模式）」相交时，canvas 的 clip 会改变边界像素的子像素覆盖率，
+ * 产生与全量渲染不一致的接缝。因此 v1 约定：本帧区域涉及任何非不透明落墨的组件时回退全量，
+ * 局部重绘只服务于不透明场景（编辑器里的大多数实体/卡片/表格）。
+ * 语义化渐变色（对象）视为不透明。
+ */
+export declare function isOpaqueDrawing(state: any): boolean;

package/dist/types/renderer/dirty-rect-util.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 脏矩形局部重绘（dirty-rect）的纯函数工具集。
+ *
+ * 本模块不依赖任何引擎实例/ctx，所有几何与阈值计算都可用 jest 直接单测。
+ * 设计目标见 docs/architecture/04-rendering-performance.md「脏矩形局部重绘」章节。
+ *
+ * 盒的表示：一维数组 [minX, minY, maxX, maxY]（世界/画布坐标，轴对齐，已含 paint pad）。
+ */
+/** 抗锯齿兜底余量（px），覆盖 1px 级 AA 溢出与文字 baseline 溢出。 */
+export declare const PAD_AA = 2;
+/**
+ * 命中预筛的包围盒容差（px）。
+ *
+ * 命中的第一道筛子用「渲染快照的世界盒」做 O(1) 拒绝；快照盒本身已含 paint pad
+ * （含 AA 余量），但折线的命中判定自带 errorRange 容差，这里再放宽 1px 作为安全余量，
+ * 确保预筛绝不误杀边界命中。
+ */
+export declare const HIT_BOX_TOLERANCE = 1;
+/**
+ * 计算组件「实际绘制会溢出几何边界多少像素」的保守 padding。
+ * 依据 state（style.lineWidth / lineBorderWidth / shadow 等）实时估算，
+ * 用于把几何包围盒扩成「真实落墨盒」。
+ */
+export declare function stylePaintPad(state: any): number;
+export declare function boxWidth(box: number[]): number;
+export declare function boxHeight(box: number[]): number;
+export declare function boxArea(box: number[]): number;
+/**
+ * 把 src 盒并进 target 盒（原地修改 target，减少分配）。
+ * target 传入空盒（[Infinity,Infinity,-Infinity,-Infinity]）即可从 src 开始累加。
+ */
+export declare function unionBoxes(target: number[], src: number[]): number[];
+/** 判断盒 a 与盒 b 是否相交（含边界相触）。 */
+export declare function intersects(a: number[], b: number[]): boolean;
+/**
+ * 盒内是否有限（无 NaN/Infinity）。非法盒不得参与区域计算或写入快照。
+ */
+export declare function isFiniteBox(box: number[]): boolean;
+/**
+ * 生成一个「空盒」，可用作 unionBoxes 的起点。
+ */
+export declare function emptyBox(): number[];
+/**
+ * 把盒外扩到整像素边界（min 向下取整、max 向上取整），保证 clearRect/clip 用同一像素掩码，
+ * 消除「清除区域与裁剪区域亚像素不一致」导致的接缝。
+ */
+export declare function integerAlign(box: number[]): number[];
+/**
+ * 合并两个盒为一个盒（取并集，不修改入参）。
+ */
+export declare function mergeBox(a: number[], b: number[]): number[];
+export declare function coalesceRegions(boxes: number[][], maxRegions?: number): number[][];
+/**
+ * 多块裁剪区的总面积占画布的比例（用于「接近整屏则回退全量」的判定）。
+ * 各块互不相接，面积可直接相加。
+ */
+export declare function regionsAreaRatio(regions: number[][], canvasWidth: number, canvasHeight: number): number;
+/**
+ * 把「世界坐标盒」映射到「渲染坐标盒」（含 dpr），并向外取整。
+ *
+ * 渲染坐标 = 世界坐标 × 渲染视口 scale + 渲染视口 tx/ty，而 `ICE.getRenderViewport()` 已经
+ * 把 dpr 乘进 scale 与 tx/ty（见 `ICE.getRenderViewport`）。`clearRect` / `clip` 用的正是这个
+ * 坐标系，但脏区收集是在**世界坐标**里做的（上屏快照盒、组件几何盒都是世界盒），
+ * 两者只在「视口为单位变换且 dpr === 1」时才重合 —— 这个函数就是它们之间唯一的换算点。
+ *
+ * 向外取整（min 向下、max 向上）保证映射后的区域不小于真实脏区，避免缩放时边缘出现接缝。
+ */
+export declare function mapBoxToRender(box: number[], viewport: {
+    scale: number;
+    tx: number;
+    ty: number;
+}, out?: number[]): number[];
+/**
+ * 区域占画布总面积的比例，用于「接近整屏则回退全量」的判定。
+ */
+export declare function regionRatio(box: number[], canvasWidth: number, canvasHeight: number): number;
+/**
+ * 判断组件是否以「完全不透明、仅 source-over」的方式绘制。
+ *
+ * dirty-rect 用 clip 把补画限定在脏区域内；clip 边界与「半透明落墨（alpha 色 / 阴影 /
+ * globalAlpha / 合成模式）」相交时，canvas 的 clip 会改变边界像素的子像素覆盖率，
+ * 产生与全量渲染不一致的接缝。因此 v1 约定：本帧区域涉及任何非不透明落墨的组件时回退全量，
+ * 局部重绘只服务于不透明场景（编辑器里的大多数实体/卡片/表格）。
+ * 语义化渐变色（对象）视为不透明。
+ */
+export declare function isOpaqueDrawing(state: any): boolean;