ice-render 2.1.1 → 2.3.0

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

@@ -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;

package/dist/types/export/compose-layers.d.mts

@@ -0,0 +1,30 @@
+export type ComposeLayersOptions = {
+    /** 输出类型（`toDataURL` 的 MIME），默认 `image/png` */
+    type?: string;
+    /** 有损格式的质量 0~1（`image/jpeg` / `image/webp` 用） */
+    quality?: number;
+    /** 背景色（如 `'#ffffff'`）。缺省不铺背景 → 保留透明度（分层图通常需要透明背景） */
+    background?: string | null;
+    /** 输出尺寸（缺省 = 各层 canvas 中最大的那一份，单位：**设备像素**） */
+    width?: number;
+    height?: number;
+};
+/**
+ * 把多层 canvas 叠到一张离屏画布上（按数组顺序，第一层在最下面）。
+ *
+ * @returns `{ canvas, ctx, width, height }`；运行时没有离屏画布能力时抛 `ICE_UNSUPPORTED_RUNTIME`。
+ */
+export declare function composeLayersToCanvas(layers: any[], options?: ComposeLayersOptions): {
+    canvas: any;
+    ctx: any;
+    width: number;
+    height: number;
+};
+/**
+ * 多层合成为一张图（DataURL）。
+ *
+ * ```js
+ * const png = composeLayersDataURL([staticIce, animIce], { background: '#fff' });
+ * ```
+ */
+export declare function composeLayersDataURL(layers: any[], options?: ComposeLayersOptions): string;

package/dist/types/export/compose-layers.d.ts

@@ -0,0 +1,30 @@
+export type ComposeLayersOptions = {
+    /** 输出类型（`toDataURL` 的 MIME），默认 `image/png` */
+    type?: string;
+    /** 有损格式的质量 0~1（`image/jpeg` / `image/webp` 用） */
+    quality?: number;
+    /** 背景色（如 `'#ffffff'`）。缺省不铺背景 → 保留透明度（分层图通常需要透明背景） */
+    background?: string | null;
+    /** 输出尺寸（缺省 = 各层 canvas 中最大的那一份，单位：**设备像素**） */
+    width?: number;
+    height?: number;
+};
+/**
+ * 把多层 canvas 叠到一张离屏画布上（按数组顺序，第一层在最下面）。
+ *
+ * @returns `{ canvas, ctx, width, height }`；运行时没有离屏画布能力时抛 `ICE_UNSUPPORTED_RUNTIME`。
+ */
+export declare function composeLayersToCanvas(layers: any[], options?: ComposeLayersOptions): {
+    canvas: any;
+    ctx: any;
+    width: number;
+    height: number;
+};
+/**
+ * 多层合成为一张图（DataURL）。
+ *
+ * ```js
+ * const png = composeLayersDataURL([staticIce, animIce], { background: '#fff' });
+ * ```
+ */
+export declare function composeLayersDataURL(layers: any[], options?: ComposeLayersOptions): string;

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

@@ -408,7 +408,43 @@ declare abstract class ICEComponent extends ICEEventTarget {
      *
      * @param newState
      */
-    setState(newState: any): void;
+    setState(newState: any, options?: {
+        paramsDirty?: boolean;
+    }): void;
+    /**
+     * 「动画安全键」白名单：写这些 state 键**不会改变派生参数**（尺寸 / 点集 / 文本量测），
+     * 因此动画/高频写值可以跳过 `paramsDirty` —— 省一次重量测，并且保住离屏位图的纯平移复用。
+     *
+     * 判定方向很重要：**未声明的键一律当作"影响派生参数"**（保守）。这样漏判只会少一点优化，
+     * 不会让尺寸/点集停在旧值上；第三方组件不声明就等于维持旧行为（每帧都置脏）。
+     * 子类覆盖时应把基类的键并入（也允许更窄，例如文本把字号/字间距/行高那类量测相关 style 键排除在外）。
+     */
+    static readonly ANIMATION_SAFE_KEYS: readonly string[];
+    /**
+     * 运行时挂上/改写一条属性动画（免"必须在构造时声明 `animations`"）。
+     *
+     * 关键细节：**写时复制**。没在构造时传 `animations` 的组件，`props.animations` 继承的是
+     * `DEFAULT_PROPS.animations`（**冻结的共享默认对象**）—— 直接 `props.animations[key] = cfg`
+     * 在严格模式下会抛 "Cannot add property …: object is not extensible"。这里先把默认对象复制成
+     * 实例自己的、可扩展的对象再写，并顺手把组件纳入 `AnimationManager`（否则动画不会推进）。
+     *
+     * ```js
+     * card.setAnimation('style.globalAlpha', { from: 0, to: 1, duration: 300 });
+     * ```
+     */
+    setAnimation(key: string, config: any): this;
+    /** 运行时摘掉一条属性动画（组件没在动画里就什么都不做）。 */
+    removeAnimation(key: string): this;
+    /** 该 state 键路径是否在「动画安全键」白名单里（`transform` 这类前缀按 `transform.xxx` 匹配）。 */
+    isAnimationSafeKey(path: string): boolean;
+    /**
+     * 按**类**查询某个 state 键路径是否"动画安全"（不需要实例）。
+     *
+     * 给下游用（DSL / Agent 侧校验）：它们手里只有类型（`ICEText` / `ICERect`…），
+     * 没有也不该造实例 —— 但需要给出"这个属性动画会每帧重量测"这类性能提示。
+     * 判定口径与实例方法完全一致（只查静态白名单）。
+     */
+    static isAnimationSafeKeyFor(ctor: any, path: string): boolean;
     /**
      * `setState` 的**前置**钩子：必须在 `merge(this.state, newState)` 之前调用（要对比新旧值）。
      *

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

@@ -408,7 +408,43 @@ declare abstract class ICEComponent extends ICEEventTarget {
      *
      * @param newState
      */
-    setState(newState: any): void;
+    setState(newState: any, options?: {
+        paramsDirty?: boolean;
+    }): void;
+    /**
+     * 「动画安全键」白名单：写这些 state 键**不会改变派生参数**（尺寸 / 点集 / 文本量测），
+     * 因此动画/高频写值可以跳过 `paramsDirty` —— 省一次重量测，并且保住离屏位图的纯平移复用。
+     *
+     * 判定方向很重要：**未声明的键一律当作"影响派生参数"**（保守）。这样漏判只会少一点优化，
+     * 不会让尺寸/点集停在旧值上；第三方组件不声明就等于维持旧行为（每帧都置脏）。
+     * 子类覆盖时应把基类的键并入（也允许更窄，例如文本把字号/字间距/行高那类量测相关 style 键排除在外）。
+     */
+    static readonly ANIMATION_SAFE_KEYS: readonly string[];
+    /**
+     * 运行时挂上/改写一条属性动画（免"必须在构造时声明 `animations`"）。
+     *
+     * 关键细节：**写时复制**。没在构造时传 `animations` 的组件，`props.animations` 继承的是
+     * `DEFAULT_PROPS.animations`（**冻结的共享默认对象**）—— 直接 `props.animations[key] = cfg`
+     * 在严格模式下会抛 "Cannot add property …: object is not extensible"。这里先把默认对象复制成
+     * 实例自己的、可扩展的对象再写，并顺手把组件纳入 `AnimationManager`（否则动画不会推进）。
+     *
+     * ```js
+     * card.setAnimation('style.globalAlpha', { from: 0, to: 1, duration: 300 });
+     * ```
+     */
+    setAnimation(key: string, config: any): this;
+    /** 运行时摘掉一条属性动画（组件没在动画里就什么都不做）。 */
+    removeAnimation(key: string): this;
+    /** 该 state 键路径是否在「动画安全键」白名单里（`transform` 这类前缀按 `transform.xxx` 匹配）。 */
+    isAnimationSafeKey(path: string): boolean;
+    /**
+     * 按**类**查询某个 state 键路径是否"动画安全"（不需要实例）。
+     *
+     * 给下游用（DSL / Agent 侧校验）：它们手里只有类型（`ICEText` / `ICERect`…），
+     * 没有也不该造实例 —— 但需要给出"这个属性动画会每帧重量测"这类性能提示。
+     * 判定口径与实例方法完全一致（只查静态白名单）。
+     */
+    static isAnimationSafeKeyFor(ctor: any, path: string): boolean;
     /**
      * `setState` 的**前置**钩子：必须在 `merge(this.state, newState)` 之前调用（要对比新旧值）。
      *

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
      * {
@@ -26,6 +32,28 @@ declare class ICEText extends ICEComponent {
      * @param props
      */
     constructor(props?: any);
+    /** 用户没显式给 width → 宽度按量测自适应 */
+    private __autoWidth;
+    /** 用户没显式给 height → 高度按量测自适应 */
+    private __autoHeight;
+    /**
+     * 逐行宽度缓存（第 8 项）：量测时顺手记下（`__measureByCanvas` 本来就要逐行 measureText），
+     * 供居中 / 右对齐、文本装饰线、SVG 导出、光标与选区复用。
+     *
+     * 失效策略：`setState`（任何 state 变化都会置 `paramsDirty`）与 `remeasureText()` 清空；
+     * 另外缓存带 key（内容 + 字体 + 字间距），即使漏清也能自我纠正。
+     */
+    private __lineWidthCache;
+    /**
+     * 最近一次量测得到的**字形墨迹**上下沿（相对基线；来自 `actualBoundingBoxAscent/Descent`）
+     * 与**字体 em 盒**上下沿（`fontBoundingBox*`，部分运行时没有则按字号粗估）。
+     *
+     * 光标 / 选区 / 命中都要把「行带」换算成屏幕上的矩形，而 canvas 的 `textBaseline` 有
+     * top / middle / bottom / alphabetic 几种口径（`y` 分别指 em 顶 / em 中 / em 底 / 字母基线）——
+     * 只按 `y + 行号 × 行高` 推会在非 bottom 基线（如 `textBaseline: 'top'`）下整体错位半行到一行。
+     */
+    private __inkMetrics;
+    private __fontMetrics;
     protected static arrangeParam(props: any): any;
     /**
      * @overwrite
@@ -52,6 +80,9 @@ declare class ICEText extends ICEComponent {
     /**
      * 创建透明的 HTML input 覆盖在文本上，捕获输入（含中文 IME）。
      * input 文字设为透明（canvas 负责显示），只保留可见光标。
+     *
+     * `multiline`（或文本里已有 `\n`）时改用 `<textarea>`：回车插入换行而不是提交，
+     * 选区 / 换行都由浏览器接管（与单行输入同一套「文字透明、只保留光标」的做法）。
      */
     private __mountEditInput;
     /**
@@ -67,13 +98,82 @@ declare class ICEText extends ICEComponent {
      */
     setText(text: string): this;
     getText(): string;
+    /**
+     * 度量前提变了（自定义字体加载完成、主题换字号…）时调用：只标脏，
+     * 真正的重算交给下一次 render（`paramsDirty → calcComponentParams → measureText`）。
+     * 见 `ICE.remeasureTexts()` 与 `ICE.loadFont()`。
+     */
+    remeasureText(): this;
+    /**
+     * 外部**显式**设置 width/height（应用代码，或布局管理器按容器分配尺寸）时，关掉对应方向的
+     * 自动量测 —— 否则下一帧 `measureText → __applyMeasuredSize` 会把刚设的尺寸又改回去，
+     * 表现为「setState({width}) 不生效」。
+     *
+     * 与构造函数里「用户是否显式传 width/height」是同一套语义（见 __autoWidth/__autoHeight）。
+     */
+    protected __beforeStateMerge(newState: any): boolean;
     /**
      * @overwrite
      * 编辑态下接管键盘输入：字符插入 / Backspace / Delete / 方向键移动光标 / Enter 提交。
      */
     protected keyboardEvtHandler(evt: any): void;
+    /** caret 之前最近的一个 grapheme 边界（无 DOM 时按 grapheme 移动/退格；DOM 由浏览器负责）。 */
+    private __prevGraphemeBoundary;
+    /** caret 之后最近的一个 grapheme 边界。 */
+    private __nextGraphemeBoundary;
+    /** 编辑态是否按多行处理：显式 `multiline`，或文本里已经存在 `\n`。 */
+    private __isMultilineEditing;
+    /**
+     * 每一行的**行盒**（组件本地坐标，原点在盒子中心）：文字左边缘 `x`、行宽 `width`、行带 `top/height`。
+     *
+     * 三处共用它，避免各算一遍又漂移：光标（renderCaret）、选区（renderSelection）、
+     * 坐标 → 下标（getCaretIndexAt）/ 编辑态命中（containsLocalPoint）。
+     * 行宽走缓存（第 8 项），不再逐帧 measureText。
+     */
+    private __lineBoxes;
+    /**
+     * 选中区间（`selectionStart` → `selectionEnd`，按原始文本下标；-1 表示没有选区）。
+     *
+     * 选区是**编辑**语义：按 `\n` 拆行定位与 `caretIndex` 一致；开启 `wrap` 的非编辑态下
+     * 显示行与原始下标不再一一对应（此时不绘制选区，避免画到错误的位置）。
+     */
+    getSelection(): {
+        start: number;
+        end: number;
+    };
+    /** 设置选区（终点省略时 = 光标位置，即「没有选中内容」）；DOM 编辑态会同步给 HTML 输入元素。 */
+    setSelection(start: number, end?: number): this;
+    /** 全选。 */
+    selectAll(): this;
+    /** 清空选区（保留光标）。 */
+    clearSelection(): this;
+    /**
+     * 本地坐标 → 光标下标（**按字形**）。
+     *
+     * 先按 y 选中行带（行外取最近的一行），再在该行的 grapheme 边界里取**离点击点最近的**一个
+     * —— 判定用相邻边界的**中点**（点过中点才开始算下一个字符），这是各主流文本编辑器的手感。
+     * 返回值是**原始文本**里的下标（含 `\n` 偏移），可直接喂给 `caretIndex`。
+     */
+    getCaretIndexAt(localX: number, localY: number): number;
     /**
-     * 在编辑态下渲染光标（垂直竖线），位置由 caretIndex + ctx.measureText 计算。
+     * 编辑态下按**文本行**命中（而不是整个盒子）：点在行带之外（如 padding / 盒子右下空白）不算命中。
+     * 非编辑态仍是盒子语义 —— 拖动、框选、双击进入编辑这些既有交互都依赖它。
+     */
+    protected containsLocalPoint(localX: number, localY: number): boolean;
+    /**
+     * 绘制选区底色（无 DOM 运行时没有浏览器选区；DOM 编辑态下浏览器 input/textarea 自己会画）。
+     */
+    private renderSelection;
+    /**
+     * 在编辑态下渲染光标（垂直竖线）。
+     *
+     * 无 DOM 的运行时（小程序 / Node）没有浏览器 caret 可用，这里自己算位置，三条规则：
+     * - **多行**：`caretIndex` 先按 `\n` 折成「第几行 + 行内偏移」，光标画在对应行（旧实现把整段前缀
+     *   都量在一个位置上，多行文本里光标会跑到第一行）；
+     * - **方向**：RTL 行的阅读起点在右，光标 x 要从右边缘往左量（`rightEdge - measure(前缀)`）；
+     * - **对齐**：与 `getRenderLines()` 同一套（left / center / right，start/end 已按方向解析）。
+     *
+     * DOM 编辑态直接返回 —— 那时光标由 HTML input 的 `caretColor` 接管（浏览器处理 grapheme / IME 更准）。
      */
     private renderCaret;
     /**
@@ -118,13 +218,30 @@ declare class ICEText extends ICEComponent {
     private __computeWrappedLines;
     /** 统一的测宽函数：优先 ctx.measureText；无 ctx 时按 fontSize 粗估。 */
     private __measureFn;
+    /** 字号（px）：所有相对单位（em / %）与默认行高都按它折算。 */
+    private __fontSizePx;
+    /** 把 `style.letterSpacing`（数字 / '2px' / '0.2em' / '20%'）归一成 CSS 值写进 ctx。 */
+    private __applyLetterSpacingToCtx;
+    /**
+     * 每一行的行高（px）：
+     * - 显式配置（数字 px / 字符串）→ 用它，单行也照用（盒子高度可预测）；
+     * - 未配置 → `max(墨迹高, 字号 × 1.35)`（见 LINE_HEIGHT_RATIO 的注释）。
+     */
+    private __lineAdvance;
     /**
      * 按 grapheme cluster 切分。
      * 优先 Intl.Segmenter（Baseline 2024），能把 emoji / ZWJ 序列 / 组合字符合成一个单元；
      * 不可用时退化为码点切分（至少不会把代理对拆开）。
+     *
+     * 实现放在 `text-wrap.ts`（断行策略共用同一份切分 + 缓存）。
      */
     private __graphemes;
-    /** 贪心换行：逐 grapheme 累加，超过可用宽度即断行。保留段落自身的 \n。 */
+    /**
+     * 换行：保留段落自身的 `\n`，段内按 `state.wordBreak` 策略断行。
+     *
+     * 断行规则是**排版**职责（见 `text-wrap.ts`）：`'normal'` 下拉丁词不被硬拆、CJK 逐字断并做禁则；
+     * `'break-all'` 保留旧的逐 grapheme 贪心。i18n 词条本身由应用层提供，这里不做任何文本加工。
+     */
     private __wrapText;
     /**
      * 超过 maxLines 时截断末行并追加省略号；逐 grapheme 回退直到「内容+省略号」放得下。
@@ -135,6 +252,14 @@ declare class ICEText extends ICEComponent {
     private __applyMeasuredSize;
     /** DOM 降级测量：line-height 归一为 1，减少 leading 干扰（旧环境/小程序）。 */
     private __measureByDOM;
+    /** 行宽缓存的 key：行内容 + 字体 + 字间距（三者任一变了，行宽就不可信）。 */
+    private __lineWidthsKey;
+    /** 记下量测阶段算好的行宽（`__measureByCanvas` 专用）。 */
+    private __cacheLineWidths;
+    /**
+     * 取逐行宽度：命中缓存直接返回；未命中也**只量这一次**（结果写回缓存）。
+     */
+    private __lineWidths;
     /**
      * 文本的**渲染行布局**：每一行的内容与基线坐标（组件本地坐标）。
      *
@@ -154,5 +279,32 @@ declare class ICEText extends ICEComponent {
      * 同时把移动坐标轴原点的偏移量计算进去。
      */
     protected doRender(): void;
+    /**
+     * 自绘文本装饰线。
+     *
+     * - 横向范围取**每一行自己的宽度**（缓存里的行宽，必要时补量一次），居右/居中/RTL 下才对得上文字；
+     * - 基线偏移按字号比例：下划线 `+0.12em`、删除线 `-0.30em`、上划线 `-0.80em`（与主流排版接近）；
+     * - 颜色：`style.textDecorationColor` 优先，留空跟随 `fillStyle`；粗细 `style.textDecorationWidth`
+     *   留 0 时按 `字号 / 14`（至少 1px）。
+     */
+    private __drawTextDecoration;
+    /**
+     * `direction: 'auto'` 需要按文本解析成具体的 ltr/rtl —— canvas 只认 `ltr | rtl | inherit`，
+     * 所以这里在通用 style 应用之后覆盖一次（`style.direction` 的原始值 `'auto'` 不会被 canvas 采纳）。
+     *
+     * 特性检测用 `'direction' in ctx`（不读值）：**不支持 `direction` 的运行时**（部分小程序基础库、
+     * 极简测试桩）就跳过，退化为默认 LTR —— 这也是小程序「Canvas 2D 子集」回归能通过的原因。
+     */
+    protected applyStyleToCtx(): void;
+    /** 本帧是否把 `ctx.direction` 写过（用于渲染结束后的归位）。 */
+    private __directionApplied;
+    /**
+     * @overwrite
+     * 除基类的泄漏属性外，`direction` 也要归位 —— 否则 RTL 文本会把方向"漏"给后面绘制的组件，
+     * 破坏「组件渲染自包含」这条铁律（脏矩形局部重绘与离屏缓存都依赖它）。
+     */
+    __resetLeakyCtxState(): void;
+    /** 解析后的文字方向（`'auto'` → 按首个强方向字符判定）。 */
+    private __resolvedDirection;
 }
 export default ICEText;