ice-render 1.2.0 → 1.4.0

package/dist/types/graphic/ICEComponent.d.mts

@@ -42,6 +42,8 @@ declare abstract class ICEComponent extends ICEEventTarget {
     /** 可见性缓存（代际号 + 值）：见 `isEffectivelyVisible` 的说明。 */
     private __visEpoch;
     private __visValue;
+    /** 本帧是否因为子树不透明度过 ctx.globalAlpha（见 __renderCore / __resetLeakyCtxState）。 */
+    private __opacityApplied;
     /** 声明式渐变缓存：按描述对象引用判定，`refreshParams()` 里失效（setState 必然触发它）。 */
     private __gradCache;
     /**
@@ -299,6 +301,12 @@ declare abstract class ICEComponent extends ICEEventTarget {
      * 顶层组件直接 O(1) 返回。
      */
     hasClippingAncestor(): boolean;
+    /**
+     * 有效不透明度 = 自身 `state.opacity` × 所有祖先的 `state.opacity`（默认 1）。
+     *
+     * 顶层组件直接返回（绝大多数组件没有祖先，热路径上不做遍历）；非法值按 1 处理。
+     */
+    private __effectiveOpacity;
     /**
      * 世界坐标点是否落在某个「裁剪祖先」的盒子之外。
      *
@@ -329,6 +337,18 @@ declare abstract class ICEComponent extends ICEEventTarget {
     protected doRender(): void;
     /** 判断两个边界盒是否在视觉上重合（用于避免重复绘制几乎相同的 min/max 框）。 */
     private __areBoundingBoxesNearlyEqual;
+    /**
+     * 内部子组件是否为「由自身 state 派生」的。
+     *
+     * 复合组件（构造时按 state 建立内部子组件的组件，如「卡片 = 底框 + 标题」）应当返回 true：
+     * 这些子组件在反序列化时会被构造函数重建，序列化它们只会造成**重复挂载**
+     * （先由构造函数建一份、再由 Deserializer 挂一份）、并且子组件的自动 zIndex 每次都会变，
+     * 让同一份数据的两次序列化结果不稳定。返回 true 后，Serializer / Deserializer 都会跳过
+     * 该组件的 childNodes —— 只持久化它自己的 state（真相源），子组件视为派生结果。
+     *
+     * 默认为 false（普通容器/叶子组件的子节点是「真数据」，必须序列化）。
+     */
+    hasDerivedChildren(): boolean;
     /**
      * 获取组件的最小包围盒，此盒子的变换矩阵与组件自身完全相同。
      * 此方法需要在 render() 之后调用，组件没有渲染时无法计算最小包围盒。

package/dist/types/graphic/ICEComponent.d.ts

@@ -42,6 +42,8 @@ declare abstract class ICEComponent extends ICEEventTarget {
     /** 可见性缓存（代际号 + 值）：见 `isEffectivelyVisible` 的说明。 */
     private __visEpoch;
     private __visValue;
+    /** 本帧是否因为子树不透明度过 ctx.globalAlpha（见 __renderCore / __resetLeakyCtxState）。 */
+    private __opacityApplied;
     /** 声明式渐变缓存：按描述对象引用判定，`refreshParams()` 里失效（setState 必然触发它）。 */
     private __gradCache;
     /**
@@ -299,6 +301,12 @@ declare abstract class ICEComponent extends ICEEventTarget {
      * 顶层组件直接 O(1) 返回。
      */
     hasClippingAncestor(): boolean;
+    /**
+     * 有效不透明度 = 自身 `state.opacity` × 所有祖先的 `state.opacity`（默认 1）。
+     *
+     * 顶层组件直接返回（绝大多数组件没有祖先，热路径上不做遍历）；非法值按 1 处理。
+     */
+    private __effectiveOpacity;
     /**
      * 世界坐标点是否落在某个「裁剪祖先」的盒子之外。
      *
@@ -329,6 +337,18 @@ declare abstract class ICEComponent extends ICEEventTarget {
     protected doRender(): void;
     /** 判断两个边界盒是否在视觉上重合（用于避免重复绘制几乎相同的 min/max 框）。 */
     private __areBoundingBoxesNearlyEqual;
+    /**
+     * 内部子组件是否为「由自身 state 派生」的。
+     *
+     * 复合组件（构造时按 state 建立内部子组件的组件，如「卡片 = 底框 + 标题」）应当返回 true：
+     * 这些子组件在反序列化时会被构造函数重建，序列化它们只会造成**重复挂载**
+     * （先由构造函数建一份、再由 Deserializer 挂一份）、并且子组件的自动 zIndex 每次都会变，
+     * 让同一份数据的两次序列化结果不稳定。返回 true 后，Serializer / Deserializer 都会跳过
+     * 该组件的 childNodes —— 只持久化它自己的 state（真相源），子组件视为派生结果。
+     *
+     * 默认为 false（普通容器/叶子组件的子节点是「真数据」，必须序列化）。
+     */
+    hasDerivedChildren(): boolean;
     /**
      * 获取组件的最小包围盒，此盒子的变换矩阵与组件自身完全相同。
      * 此方法需要在 render() 之后调用，组件没有渲染时无法计算最小包围盒。

package/dist/types/index.d.mts

@@ -51,5 +51,7 @@ export { default as ICE } from './ICE.mjs';
 export { default as CanvasRenderer } from './renderer/CanvasRenderer.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';
+export { default as Deserializer, SERIALIZATION_MIGRATIONS } from './persistence/Deserializer.mjs';
 export { buildAccessibilityTree } from './a11y/accessibility.mjs';
 export type { ICEAccessibleNode, ICEAccessibleRole, ICEAccessibilityOptions } from './a11y/accessibility.mjs';

package/dist/types/index.d.ts

@@ -51,5 +51,7 @@ export { default as ICE } from './ICE';
 export { default as CanvasRenderer } from './renderer/CanvasRenderer';
 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';
+export { default as Deserializer, SERIALIZATION_MIGRATIONS } from './persistence/Deserializer';
 export { buildAccessibilityTree } from './a11y/accessibility';
 export type { ICEAccessibleNode, ICEAccessibleRole, ICEAccessibilityOptions } from './a11y/accessibility';

package/package.json

@@ -1,7 +1,7 @@
 {
   "author": "大漠穷秋",
   "name": "ice-render",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "A canvas engine for interactive graphics.",
   "repository": {
     "type": "git",