ice-render 1.4.1 → 1.4.3

package/dist/types/ICE.d.mts

@@ -9,6 +9,7 @@ import Deserializer from './persistence/Deserializer.mjs';
 import Serializer from './persistence/Serializer.mjs';
 import PluginHost, { ICEPlugin } from './plugin/PluginHost.mjs';
 import { ICEAccessibleNode, ICEAccessibilityOptions } from './a11y/accessibility.mjs';
+import type { SvgExportOptions, SvgExportResult } from './export/SvgExporter.mjs';
 import ImageCache from './util/ImageCache.mjs';
 import { ICETheme, ICESemanticTheme } from './theme/ICETheme.mjs';
 /**
@@ -349,6 +350,41 @@ declare class ICE {
      * 把画布导出为 Blob（回调接收）。
      */
     toBlob(callback: (blob: Blob | null) => void, type?: string, quality?: number): void;
+    /**
+     * 把当前场景导出为 **SVG 矢量图**。
+     *
+     * 与 `toDataURL()` / `toBlob()` 的区别：那是画布的**光栅快照**（分辨率写死、缩放后糊），
+     * 这是从组件树 + 路径命令流重新生成的**矢量描述** —— 可以任意放大、丢进 Illustrator/Figma、
+     * 直接进打印/PDF 流程，也能在 Node 里生成（不需要 canvas）。
+     *
+     * 口径与画布渲染一致（顺序、矩阵、样式合并、有效透明度、祖先裁剪），细节与限制见
+     * `export/SvgExporter.ts` 的文件头。
+     *
+     * ```js
+     * const svg = ice.toSvg();                                  // 内容自适应、透明背景
+     * const svg = ice.toSvg({ background: '#fff', padding: 16 }); // 白底 + 留白
+     * const svg = ice.toSvg({ area: 'viewport' });               // 当前视口所见即所得
+     * ```
+     */
+    toSvg(options?: SvgExportOptions): string;
+    /**
+     * 创建一个**不依赖 canvas 的 ICE 实例**：服务端出图 / 无头批处理的入口。
+     *
+     * 它和 `init()` 出来的实例共用同一套组件树、矩阵、样式与导出逻辑，只是没有渲染器、
+     * 没有输入派发、也没有 rAF 帧循环 —— 因此能在 Node 里 `new` 完就 `addChild` + `toSvg()`。
+     *
+     * ```js
+     * const ice = ICE.headless();
+     * ice.addChild(new ICERect({ width: 100, height: 50, style: { fillStyle: '#4f46e5' } }));
+     * const svg = ice.toSvg();
+     * ```
+     *
+     * 注意：没有渲染循环，意味着**派生几何**（折线的点、文本的换行行）由导出器在导出时刷新
+     * （见 SvgExporter 里的 refreshParams/ensurePathBuilt），而不是靠帧循环。
+     */
+    static headless(): ICE;
+    /** 同 `toSvg()`，但额外返回计算出的画布尺寸（写文件 / 布局预览要用的宽高） */
+    toSvgResult(options?: SvgExportOptions): SvgExportResult;
     /**
      * 把对象序列化成 JSON 字符串：
      * - 容器型组件需要负责子节点的序列化操作

package/dist/types/ICE.d.ts

@@ -9,6 +9,7 @@ import Deserializer from './persistence/Deserializer';
 import Serializer from './persistence/Serializer';
 import PluginHost, { ICEPlugin } from './plugin/PluginHost';
 import { ICEAccessibleNode, ICEAccessibilityOptions } from './a11y/accessibility';
+import type { SvgExportOptions, SvgExportResult } from './export/SvgExporter';
 import ImageCache from './util/ImageCache';
 import { ICETheme, ICESemanticTheme } from './theme/ICETheme';
 /**
@@ -349,6 +350,41 @@ declare class ICE {
      * 把画布导出为 Blob（回调接收）。
      */
     toBlob(callback: (blob: Blob | null) => void, type?: string, quality?: number): void;
+    /**
+     * 把当前场景导出为 **SVG 矢量图**。
+     *
+     * 与 `toDataURL()` / `toBlob()` 的区别：那是画布的**光栅快照**（分辨率写死、缩放后糊），
+     * 这是从组件树 + 路径命令流重新生成的**矢量描述** —— 可以任意放大、丢进 Illustrator/Figma、
+     * 直接进打印/PDF 流程，也能在 Node 里生成（不需要 canvas）。
+     *
+     * 口径与画布渲染一致（顺序、矩阵、样式合并、有效透明度、祖先裁剪），细节与限制见
+     * `export/SvgExporter.ts` 的文件头。
+     *
+     * ```js
+     * const svg = ice.toSvg();                                  // 内容自适应、透明背景
+     * const svg = ice.toSvg({ background: '#fff', padding: 16 }); // 白底 + 留白
+     * const svg = ice.toSvg({ area: 'viewport' });               // 当前视口所见即所得
+     * ```
+     */
+    toSvg(options?: SvgExportOptions): string;
+    /**
+     * 创建一个**不依赖 canvas 的 ICE 实例**：服务端出图 / 无头批处理的入口。
+     *
+     * 它和 `init()` 出来的实例共用同一套组件树、矩阵、样式与导出逻辑，只是没有渲染器、
+     * 没有输入派发、也没有 rAF 帧循环 —— 因此能在 Node 里 `new` 完就 `addChild` + `toSvg()`。
+     *
+     * ```js
+     * const ice = ICE.headless();
+     * ice.addChild(new ICERect({ width: 100, height: 50, style: { fillStyle: '#4f46e5' } }));
+     * const svg = ice.toSvg();
+     * ```
+     *
+     * 注意：没有渲染循环，意味着**派生几何**（折线的点、文本的换行行）由导出器在导出时刷新
+     * （见 SvgExporter 里的 refreshParams/ensurePathBuilt），而不是靠帧循环。
+     */
+    static headless(): ICE;
+    /** 同 `toSvg()`，但额外返回计算出的画布尺寸（写文件 / 布局预览要用的宽高） */
+    toSvgResult(options?: SvgExportOptions): SvgExportResult;
     /**
      * 把对象序列化成 JSON 字符串：
      * - 容器型组件需要负责子节点的序列化操作

package/dist/types/cross-platform/Path2DRecorder.d.mts

@@ -0,0 +1,76 @@
+/**
+ * Copyright (c) 2022 大漠穷秋.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+/**
+ * @class Path2DRecorder
+ *
+ * 路径对象的**唯一入口**：一边把命令写给内存里的命令流，一边转发给运行时的原生 Path2D。
+ *
+ * 为什么需要它：原生 `Path2D` 是不透明的 —— 画得出来，但拿不到「这条路径到底是什么形状」。
+ * 而引擎的这几件事都需要**路径的几何描述**，不只是「画出来」：
+ *
+ * - 导出（SVG / 打印 / 服务端出图）：要把路径转成 `d` 属性；
+ * - 服务端 / 小程序（无原生 Path2D）：要靠命令流重放到 ctx（原先只有 PolyfillPath2D 能做到）；
+ * - 测试与调试：可以直接断言「这个形状生成了哪几条命令」，不必截图比对像素。
+ *
+ * 设计取舍：
+ * - **有原生 Path2D 时仍然用原生对象上屏**（`native`），命令流只是顺带记录，渲染路径与旧版
+ *   完全一致；`ICEPath.doRender()` 用 `path2D.native || path2D` 取上屏对象。
+ * - **没有原生 Path2D 时**（小程序低版本 / Node）退化为纯记录器：`_isPolyfill` 为真，
+ *   `ICEPath` 走「重放命令到 ctx」的老路径，行为与之前的 PolyfillPath2D 一致。
+ * - 路径是**几何变化时才重建**（`doRender` 只在 dirty 时调用 `createPathObject()`），因此
+ *   记录带来的开销只发生在路径重建时，不在每帧热路径上。
+ *
+ * 命令格式与 PolyfillPath2D 一致（也被 `replayPath()` 复用）：
+ * `[['moveTo', x, y], ['rect', x, y, w, h], ...]`
+ */
+export default class Path2DRecorder {
+    /** 标记「没有原生 Path2D，需要重放命令」——与 PolyfillPath2D 的语义保持一致 */
+    _isPolyfill: boolean;
+    /** 记录的命令序列 */
+    _commands: Array<Array<any>>;
+    /** closePath 是幂等标记（doRender 每帧调用），不重复入队 */
+    _closed: boolean;
+    /** 原生 Path2D（有则上屏直接用它，命令流仍然记录）；无则为 null */
+    readonly native: any;
+    /** 当前点（画布 arcTo / 圆弧的语义依赖它），[x, y]；空表示没有当前子路径 */
+    private __current;
+    /** 当前子路径的起点（closePath 后当前点回到这里） */
+    private __subpathStart;
+    constructor(native?: any);
+    /** 上屏对象：有原生就用原生，否则用记录器自己（配合 replayPath 重放） */
+    get drawable(): any;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
+    quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
+    /**
+     * 圆角/切线圆弧。
+     *
+     * canvas 的 `arcTo` 依赖「当前点 + 控制点 + 半径」的切线关系，**SVG 没有对应命令**。
+     * 这里在记录阶段就把它**还原成 `lineTo(切点) + arc(圆心, 半径, 起止角)`**：
+     *
+     * - 出口是标准命令流，SVG 导出（以及任何重放到 ctx 的运行时）都不需要再懂 arcTo；
+     * - 原生 Path2D 收到的是等价的 lineTo/arc，渲染结果与直接 arcTo 一致；
+     * - 圆角矩形（ICERect 的 radius）就是靠它才能导出成真正的圆角，否则导出会变成切角。
+     *
+     * 数学：设 P0 = 当前点、P1 = 控制点、P2 = 终点，u = 单位(P0−P1)、v = 单位(P2−P1)，
+     * 夹角 θ = ∠(u,v)，切点到 P1 的距离 t = r / tan(θ/2)，圆心在角平分线上距 P1 为 r / sin(θ/2)。
+     */
+    arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void;
+    rect(x: number, y: number, width: number, height: number): void;
+    /**
+     * 圆弧。**必须实现**：事件圆等形状用的是 `arc`，此前 PolyfillPath2D 没有它，
+     * 于是「无原生 Path2D」的运行时（Node / 小程序低版本）画这类形状会直接抛
+     * `path.arc is not a function` —— 这正是服务端出图要修的第一件事。
+     */
+    arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
+    ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number, startAngle: number, endAngle: number, counterclockwise: boolean): void;
+    closePath(): void;
+    /** 当前点（只读；调试与测试用） */
+    get currentPoint(): [number, number] | null;
+}

package/dist/types/cross-platform/Path2DRecorder.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Copyright (c) 2022 大漠穷秋.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+/**
+ * @class Path2DRecorder
+ *
+ * 路径对象的**唯一入口**：一边把命令写给内存里的命令流，一边转发给运行时的原生 Path2D。
+ *
+ * 为什么需要它：原生 `Path2D` 是不透明的 —— 画得出来，但拿不到「这条路径到底是什么形状」。
+ * 而引擎的这几件事都需要**路径的几何描述**，不只是「画出来」：
+ *
+ * - 导出（SVG / 打印 / 服务端出图）：要把路径转成 `d` 属性；
+ * - 服务端 / 小程序（无原生 Path2D）：要靠命令流重放到 ctx（原先只有 PolyfillPath2D 能做到）；
+ * - 测试与调试：可以直接断言「这个形状生成了哪几条命令」，不必截图比对像素。
+ *
+ * 设计取舍：
+ * - **有原生 Path2D 时仍然用原生对象上屏**（`native`），命令流只是顺带记录，渲染路径与旧版
+ *   完全一致；`ICEPath.doRender()` 用 `path2D.native || path2D` 取上屏对象。
+ * - **没有原生 Path2D 时**（小程序低版本 / Node）退化为纯记录器：`_isPolyfill` 为真，
+ *   `ICEPath` 走「重放命令到 ctx」的老路径，行为与之前的 PolyfillPath2D 一致。
+ * - 路径是**几何变化时才重建**（`doRender` 只在 dirty 时调用 `createPathObject()`），因此
+ *   记录带来的开销只发生在路径重建时，不在每帧热路径上。
+ *
+ * 命令格式与 PolyfillPath2D 一致（也被 `replayPath()` 复用）：
+ * `[['moveTo', x, y], ['rect', x, y, w, h], ...]`
+ */
+export default class Path2DRecorder {
+    /** 标记「没有原生 Path2D，需要重放命令」——与 PolyfillPath2D 的语义保持一致 */
+    _isPolyfill: boolean;
+    /** 记录的命令序列 */
+    _commands: Array<Array<any>>;
+    /** closePath 是幂等标记（doRender 每帧调用），不重复入队 */
+    _closed: boolean;
+    /** 原生 Path2D（有则上屏直接用它，命令流仍然记录）；无则为 null */
+    readonly native: any;
+    /** 当前点（画布 arcTo / 圆弧的语义依赖它），[x, y]；空表示没有当前子路径 */
+    private __current;
+    /** 当前子路径的起点（closePath 后当前点回到这里） */
+    private __subpathStart;
+    constructor(native?: any);
+    /** 上屏对象：有原生就用原生，否则用记录器自己（配合 replayPath 重放） */
+    get drawable(): any;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
+    quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
+    /**
+     * 圆角/切线圆弧。
+     *
+     * canvas 的 `arcTo` 依赖「当前点 + 控制点 + 半径」的切线关系，**SVG 没有对应命令**。
+     * 这里在记录阶段就把它**还原成 `lineTo(切点) + arc(圆心, 半径, 起止角)`**：
+     *
+     * - 出口是标准命令流，SVG 导出（以及任何重放到 ctx 的运行时）都不需要再懂 arcTo；
+     * - 原生 Path2D 收到的是等价的 lineTo/arc，渲染结果与直接 arcTo 一致；
+     * - 圆角矩形（ICERect 的 radius）就是靠它才能导出成真正的圆角，否则导出会变成切角。
+     *
+     * 数学：设 P0 = 当前点、P1 = 控制点、P2 = 终点，u = 单位(P0−P1)、v = 单位(P2−P1)，
+     * 夹角 θ = ∠(u,v)，切点到 P1 的距离 t = r / tan(θ/2)，圆心在角平分线上距 P1 为 r / sin(θ/2)。
+     */
+    arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void;
+    rect(x: number, y: number, width: number, height: number): void;
+    /**
+     * 圆弧。**必须实现**：事件圆等形状用的是 `arc`，此前 PolyfillPath2D 没有它，
+     * 于是「无原生 Path2D」的运行时（Node / 小程序低版本）画这类形状会直接抛
+     * `path.arc is not a function` —— 这正是服务端出图要修的第一件事。
+     */
+    arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
+    ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number, startAngle: number, endAngle: number, counterclockwise: boolean): void;
+    closePath(): void;
+    /** 当前点（只读；调试与测试用） */
+    get currentPoint(): [number, number] | null;
+}

package/dist/types/cross-platform/PolyfillPath2D.d.mts

@@ -5,27 +5,17 @@
  * LICENSE file in the root directory of this source tree.
  *
  */
+import Path2DRecorder from './Path2DRecorder.mjs';
 /**
  * @class PolyfillPath2D
  *
- * Path2D 的极简 polyfill：无全局 Path2D 构造函数的运行时（如小程序低版本基础库、
- * Node 环境）中，用它记录路径命令，渲染时再重放到 ctx 当前路径。
+ * 「没有原生 Path2D」时的路径实现 —— 现在只是 `Path2DRecorder` 的别名：
+ * 记录器本身就是「无原生时退化为纯命令记录」的那个实现，两者再各写一份必然会漂移
+ * （历史上这里就少了 `arc`，导致小程序低版本 / Node 里画事件圆直接抛错）。
  *
- * 仅实现引擎用到的 moveTo/lineTo/rect/ellipse/closePath，其余标准 Path2D 方法未实现。
+ * 保留类名是为了不破坏既有 import 与测试里对它的引用。
+ *
+ * @deprecated 新代码请直接用 `Path2DRecorder`（或 `root.createPath2D()`）。
  */
-export default class PolyfillPath2D {
-    /** 标记这是 polyfill，用于 ICEPath.doRender 区分原生 Path2D 与命令重放 */
-    _isPolyfill: boolean;
-    /** 记录的命令序列，如 [['rect', 0, 0, 10, 10], ['moveTo', 1, 1], ...] */
-    _commands: Array<Array<any>>;
-    /** closePath 是幂等标记（doRender 每帧调用），不重复入队 */
-    _closed: boolean;
-    moveTo(x: number, y: number): void;
-    lineTo(x: number, y: number): void;
-    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
-    quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
-    arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void;
-    rect(x: number, y: number, width: number, height: number): void;
-    ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number, startAngle: number, endAngle: number, counterclockwise: boolean): void;
-    closePath(): void;
+export default class PolyfillPath2D extends Path2DRecorder {
 }

package/dist/types/cross-platform/PolyfillPath2D.d.ts

@@ -5,27 +5,17 @@
  * LICENSE file in the root directory of this source tree.
  *
  */
+import Path2DRecorder from './Path2DRecorder';
 /**
  * @class PolyfillPath2D
  *
- * Path2D 的极简 polyfill：无全局 Path2D 构造函数的运行时（如小程序低版本基础库、
- * Node 环境）中，用它记录路径命令，渲染时再重放到 ctx 当前路径。
+ * 「没有原生 Path2D」时的路径实现 —— 现在只是 `Path2DRecorder` 的别名：
+ * 记录器本身就是「无原生时退化为纯命令记录」的那个实现，两者再各写一份必然会漂移
+ * （历史上这里就少了 `arc`，导致小程序低版本 / Node 里画事件圆直接抛错）。
  *
- * 仅实现引擎用到的 moveTo/lineTo/rect/ellipse/closePath，其余标准 Path2D 方法未实现。
+ * 保留类名是为了不破坏既有 import 与测试里对它的引用。
+ *
+ * @deprecated 新代码请直接用 `Path2DRecorder`（或 `root.createPath2D()`）。
  */
-export default class PolyfillPath2D {
-    /** 标记这是 polyfill，用于 ICEPath.doRender 区分原生 Path2D 与命令重放 */
-    _isPolyfill: boolean;
-    /** 记录的命令序列，如 [['rect', 0, 0, 10, 10], ['moveTo', 1, 1], ...] */
-    _commands: Array<Array<any>>;
-    /** closePath 是幂等标记（doRender 每帧调用），不重复入队 */
-    _closed: boolean;
-    moveTo(x: number, y: number): void;
-    lineTo(x: number, y: number): void;
-    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
-    quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
-    arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void;
-    rect(x: number, y: number, width: number, height: number): void;
-    ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number, startAngle: number, endAngle: number, counterclockwise: boolean): void;
-    closePath(): void;
+export default class PolyfillPath2D extends Path2DRecorder {
 }

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

@@ -0,0 +1,54 @@
+/**
+ * @file SVG 导出
+ *
+ * 引擎的渲染是 canvas 光栅化的，但**几何描述一直都在**：`Path2DRecorder` 让每个路径组件都持有
+ * 自己的命令流（见 cross-platform/Path2DRecorder.ts），于是同一份场景可以再输出一份矢量。
+ *
+ * 导出器刻意**镜像渲染器的口径**，而不是另起一套：
+ * - 绘制顺序 = 渲染队列的顺序（`flattenTree` 后按 `state.zIndex` 稳定排序），工具层默认不导出；
+ * - 每个组件的变换 = `composeMatrix()`（本地 → 世界），整体再套一层「世界 → 视图」矩阵，
+ *   与 `applyTransformToCtx()` 的 `viewport · composed` 完全对应；
+ * - 填充/描边 = `state.fill` / `state.stroke` + `props.style` 与 `state.style` 合并后的键
+ *   （state 覆盖 props，与 `applyStyleToCtx()` 同序）；
+ * - 透明度 = `getEffectiveOpacity()`（自身 × 祖先），与画布的 `globalAlpha` 同一口径；
+ * - 裁剪 = 祖先链上所有 `clipChildren` 的世界包围盒，与 `__applyAncestorClips()` 一致。
+ *
+ * 已支持：任意 `ICEPath` 家族（矩形/圆角矩形/椭圆/自定义形状/折线/贝塞尔/组自身背景）、
+ * 文本（多行、水平/垂直对齐、换行后的行）、图片（含圆形裁剪）、线性/径向渐变、虚线、
+ * 视口或内容自适应尺寸、透明背景。
+ *
+ * 暂未支持（有意留白，都会在文档里写明）：
+ * - 阴影（canvas 的 shadow* → SVG 需要 filter，且模糊半径语义不完全等价）；
+ * - 雪碧图切图（`sx/sy/sw/sh`）与 `fillRule` 的奇偶填充差异；
+ * - 蚂蚁线动画（导出的是**静态瞬间**，只保留当前 dash 相位）。
+ *
+ * 文本的**字形度量**在 canvas 与 SVG 之间不可能逐像素一致（字体回退、行高、基线定义不同），
+ * 因此导出器用 `text-anchor` / `dominant-baseline` 表达对齐，而不是把测出来的宽度写死；
+ * 左对齐（默认）与画布逐字对齐，居中/右对齐按锚点对齐、宽度由渲染方自己定。
+ */
+export type SvgExportOptions = {
+    /** 导出范围：`content`（默认，按内容包围盒紧凑裁切）或 `viewport`（当前画布视口） */
+    area?: 'content' | 'viewport';
+    /** `area: 'content'` 时的四周留白，默认 0 */
+    padding?: number;
+    /** 缩放倍数，默认 1（内容模式下按世界尺寸 1:1） */
+    scale?: number;
+    /** 背景色；默认不铺背景（透明） */
+    background?: string | null;
+    /** 是否把工具层（控制面板、对齐辅助线）也导出，默认 false */
+    includeTools?: boolean;
+    /** 坐标保留小数位，默认 2（避免 `d` 属性里出现一长串浮点噪声） */
+    precision?: number;
+};
+export type SvgExportResult = {
+    svg: string;
+    width: number;
+    height: number;
+};
+/**
+ * 导出场景为 SVG 字符串。
+ *
+ * @param target ICE 实例（导出整幅画布）或任意组件（导出它的子树）
+ */
+export declare function exportSvg(target: any, options?: SvgExportOptions): string;
+export declare function exportSvgResult(target: any, options?: SvgExportOptions): SvgExportResult;

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

@@ -0,0 +1,54 @@
+/**
+ * @file SVG 导出
+ *
+ * 引擎的渲染是 canvas 光栅化的，但**几何描述一直都在**：`Path2DRecorder` 让每个路径组件都持有
+ * 自己的命令流（见 cross-platform/Path2DRecorder.ts），于是同一份场景可以再输出一份矢量。
+ *
+ * 导出器刻意**镜像渲染器的口径**，而不是另起一套：
+ * - 绘制顺序 = 渲染队列的顺序（`flattenTree` 后按 `state.zIndex` 稳定排序），工具层默认不导出；
+ * - 每个组件的变换 = `composeMatrix()`（本地 → 世界），整体再套一层「世界 → 视图」矩阵，
+ *   与 `applyTransformToCtx()` 的 `viewport · composed` 完全对应；
+ * - 填充/描边 = `state.fill` / `state.stroke` + `props.style` 与 `state.style` 合并后的键
+ *   （state 覆盖 props，与 `applyStyleToCtx()` 同序）；
+ * - 透明度 = `getEffectiveOpacity()`（自身 × 祖先），与画布的 `globalAlpha` 同一口径；
+ * - 裁剪 = 祖先链上所有 `clipChildren` 的世界包围盒，与 `__applyAncestorClips()` 一致。
+ *
+ * 已支持：任意 `ICEPath` 家族（矩形/圆角矩形/椭圆/自定义形状/折线/贝塞尔/组自身背景）、
+ * 文本（多行、水平/垂直对齐、换行后的行）、图片（含圆形裁剪）、线性/径向渐变、虚线、
+ * 视口或内容自适应尺寸、透明背景。
+ *
+ * 暂未支持（有意留白，都会在文档里写明）：
+ * - 阴影（canvas 的 shadow* → SVG 需要 filter，且模糊半径语义不完全等价）；
+ * - 雪碧图切图（`sx/sy/sw/sh`）与 `fillRule` 的奇偶填充差异；
+ * - 蚂蚁线动画（导出的是**静态瞬间**，只保留当前 dash 相位）。
+ *
+ * 文本的**字形度量**在 canvas 与 SVG 之间不可能逐像素一致（字体回退、行高、基线定义不同），
+ * 因此导出器用 `text-anchor` / `dominant-baseline` 表达对齐，而不是把测出来的宽度写死；
+ * 左对齐（默认）与画布逐字对齐，居中/右对齐按锚点对齐、宽度由渲染方自己定。
+ */
+export type SvgExportOptions = {
+    /** 导出范围：`content`（默认，按内容包围盒紧凑裁切）或 `viewport`（当前画布视口） */
+    area?: 'content' | 'viewport';
+    /** `area: 'content'` 时的四周留白，默认 0 */
+    padding?: number;
+    /** 缩放倍数，默认 1（内容模式下按世界尺寸 1:1） */
+    scale?: number;
+    /** 背景色；默认不铺背景（透明） */
+    background?: string | null;
+    /** 是否把工具层（控制面板、对齐辅助线）也导出，默认 false */
+    includeTools?: boolean;
+    /** 坐标保留小数位，默认 2（避免 `d` 属性里出现一长串浮点噪声） */
+    precision?: number;
+};
+export type SvgExportResult = {
+    svg: string;
+    width: number;
+    height: number;
+};
+/**
+ * 导出场景为 SVG 字符串。
+ *
+ * @param target ICE 实例（导出整幅画布）或任意组件（导出它的子树）
+ */
+export declare function exportSvg(target: any, options?: SvgExportOptions): string;
+export declare function exportSvgResult(target: any, options?: SvgExportOptions): SvgExportResult;

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

@@ -10,6 +10,30 @@ import EventBus from '../event/EventBus.mjs';
 import ICEEventTarget from '../event/ICEEventTarget.mjs';
 import ICEBoundingBox from '../geometry/ICEBoundingBox.mjs';
 import ICE from '../ICE.mjs';
+/**
+ * 阴影简写预设：style.shadow: 'sm' | 'md' | 'lg' 一行搞定浮起效果，
+ * 对应展开为 shadowColor / shadowBlur / shadowOffsetX / shadowOffsetY。
+ */
+export declare const SHADOW_PRESETS: {
+    sm: {
+        shadowColor: string;
+        shadowBlur: number;
+        shadowOffsetX: number;
+        shadowOffsetY: number;
+    };
+    md: {
+        shadowColor: string;
+        shadowBlur: number;
+        shadowOffsetX: number;
+        shadowOffsetY: number;
+    };
+    lg: {
+        shadowColor: string;
+        shadowBlur: number;
+        shadowOffsetX: number;
+        shadowOffsetY: number;
+    };
+};
 declare abstract class ICEComponent extends ICEEventTarget {
     ice: ICE;
     root: any;
@@ -298,7 +322,13 @@ declare abstract class ICEComponent extends ICEEventTarget {
      *
      * 顶层组件直接返回（绝大多数组件没有祖先，热路径上不做遍历）；非法值按 1 处理。
      */
-    private __effectiveOpacity;
+    /**
+     * 有效不透明度 = 自身 `state.opacity` × 所有祖先的 `state.opacity`（默认 1）。
+     *
+     * 渲染把相乘的结果叠到 `ctx.globalAlpha` 上（祖先的 opacity 不会自动继承，组件是逐个绘制的）。
+     * 公开出来是因为**离屏与 SVG 导出必须用同一口径**，否则导出的图会比画布亮/暗一截。
+     */
+    getEffectiveOpacity(): number;
     /**
      * 世界坐标点是否落在某个「裁剪祖先」的盒子之外。
      *

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

@@ -10,6 +10,30 @@ import EventBus from '../event/EventBus';
 import ICEEventTarget from '../event/ICEEventTarget';
 import ICEBoundingBox from '../geometry/ICEBoundingBox';
 import ICE from '../ICE';
+/**
+ * 阴影简写预设：style.shadow: 'sm' | 'md' | 'lg' 一行搞定浮起效果，
+ * 对应展开为 shadowColor / shadowBlur / shadowOffsetX / shadowOffsetY。
+ */
+export declare const SHADOW_PRESETS: {
+    sm: {
+        shadowColor: string;
+        shadowBlur: number;
+        shadowOffsetX: number;
+        shadowOffsetY: number;
+    };
+    md: {
+        shadowColor: string;
+        shadowBlur: number;
+        shadowOffsetX: number;
+        shadowOffsetY: number;
+    };
+    lg: {
+        shadowColor: string;
+        shadowBlur: number;
+        shadowOffsetX: number;
+        shadowOffsetY: number;
+    };
+};
 declare abstract class ICEComponent extends ICEEventTarget {
     ice: ICE;
     root: any;
@@ -298,7 +322,13 @@ declare abstract class ICEComponent extends ICEEventTarget {
      *
      * 顶层组件直接返回（绝大多数组件没有祖先，热路径上不做遍历）；非法值按 1 处理。
      */
-    private __effectiveOpacity;
+    /**
+     * 有效不透明度 = 自身 `state.opacity` × 所有祖先的 `state.opacity`（默认 1）。
+     *
+     * 渲染把相乘的结果叠到 `ctx.globalAlpha` 上（祖先的 opacity 不会自动继承，组件是逐个绘制的）。
+     * 公开出来是因为**离屏与 SVG 导出必须用同一口径**，否则导出的图会比画布亮/暗一截。
+     */
+    getEffectiveOpacity(): number;
     /**
      * 世界坐标点是否落在某个「裁剪祖先」的盒子之外。
      *

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

@@ -6,6 +6,13 @@ import ICEComponent from './ICEComponent.mjs';
  */
 declare abstract class ICEPath extends ICEComponent {
     path2D: any;
+    /**
+     * 确保路径命令流是最新的。
+     *
+     * 画布通道里由 `doRender()` 在 dirty 时重建；但**导出 / 服务端出图没有渲染循环**
+     * （Node 里连 canvas 都没有），此时必须显式建一次，否则命令流是空的、导出出来一片空白。
+     */
+    ensurePathBuilt(): void;
     /**
      * @cfg
      * {

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

@@ -6,6 +6,13 @@ import ICEComponent from './ICEComponent';
  */
 declare abstract class ICEPath extends ICEComponent {
     path2D: any;
+    /**
+     * 确保路径命令流是最新的。
+     *
+     * 画布通道里由 `doRender()` 在 dirty 时重建；但**导出 / 服务端出图没有渲染循环**
+     * （Node 里连 canvas 都没有），此时必须显式建一次，否则命令流是空的、导出出来一片空白。
+     */
+    ensurePathBuilt(): void;
     /**
      * @cfg
      * {

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

@@ -91,6 +91,15 @@ declare class ICEText extends ICEComponent {
         width: any;
         height: any;
     };
+    /**
+     * 多行文本的行距系数。
+     *
+     * 为什么不能直接用 `actualBoundingBoxAscent + Descent`（字形墨迹高度）当行距：
+     * 墨迹只覆盖「有笔画的部分」，拉丁字母的 cap-height 比 em 小得多 —— 14px Tahoma 的
+     * 墨迹高 ≈ 12px，拿它当行距时中文（墨迹接近满 em）会**上下叠在一起**，看起来像文字被压扁。
+     * 按字号 × 1.35 取行距更接近系统的自然行高，同时保证 ≥ 墨迹高度（不会挤）。
+     */
+    private static readonly LINE_HEIGHT_RATIO;
     /**
      * @method measureText
      *
@@ -126,6 +135,18 @@ declare class ICEText extends ICEComponent {
     private __applyMeasuredSize;
     /** DOM 降级测量：line-height 归一为 1，减少 leading 干扰（旧环境/小程序）。 */
     private __measureByDOM;
+    /**
+     * 文本的**渲染行布局**：每一行的内容与基线坐标（组件本地坐标）。
+     *
+     * 画布渲染与 SVG 导出共用这一份口径 —— 两处各算一遍必然漂移（改了对齐公式忘了另一处，
+     * 表现为「导出的文字整体偏移」）。返回的 `x` 是**文字左边缘**（左/居中/右对齐都按画布公式算好），
+     * `y` 是 baseline 位置。
+     */
+    getRenderLines(): Array<{
+        text: string;
+        x: number;
+        y: number;
+    }>;
     /**
      * @method doRender
      * @overwrite

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

@@ -91,6 +91,15 @@ declare class ICEText extends ICEComponent {
         width: any;
         height: any;
     };
+    /**
+     * 多行文本的行距系数。
+     *
+     * 为什么不能直接用 `actualBoundingBoxAscent + Descent`（字形墨迹高度）当行距：
+     * 墨迹只覆盖「有笔画的部分」，拉丁字母的 cap-height 比 em 小得多 —— 14px Tahoma 的
+     * 墨迹高 ≈ 12px，拿它当行距时中文（墨迹接近满 em）会**上下叠在一起**，看起来像文字被压扁。
+     * 按字号 × 1.35 取行距更接近系统的自然行高，同时保证 ≥ 墨迹高度（不会挤）。
+     */
+    private static readonly LINE_HEIGHT_RATIO;
     /**
      * @method measureText
      *
@@ -126,6 +135,18 @@ declare class ICEText extends ICEComponent {
     private __applyMeasuredSize;
     /** DOM 降级测量：line-height 归一为 1，减少 leading 干扰（旧环境/小程序）。 */
     private __measureByDOM;
+    /**
+     * 文本的**渲染行布局**：每一行的内容与基线坐标（组件本地坐标）。
+     *
+     * 画布渲染与 SVG 导出共用这一份口径 —— 两处各算一遍必然漂移（改了对齐公式忘了另一处，
+     * 表现为「导出的文字整体偏移」）。返回的 `x` 是**文字左边缘**（左/居中/右对齐都按画布公式算好），
+     * `y` 是 baseline 位置。
+     */
+    getRenderLines(): Array<{
+        text: string;
+        x: number;
+        y: number;
+    }>;
     /**
      * @method doRender
      * @overwrite

package/dist/types/index.d.mts

@@ -49,6 +49,8 @@ export { default as ICELayeredLayout } from './layout/ICELayeredLayout.mjs';
 export { default as ICETheme, baseTokens, DEFAULT_THEME, DARK_THEME, registerTheme, setTheme, getTheme, STYLE_PRESETS, } from './theme/ICETheme.mjs';
 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 { 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

@@ -49,6 +49,8 @@ export { default as ICELayeredLayout } from './layout/ICELayeredLayout';
 export { default as ICETheme, baseTokens, DEFAULT_THEME, DARK_THEME, registerTheme, setTheme, getTheme, STYLE_PRESETS, } from './theme/ICETheme';
 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 { default as PluginHost } from './plugin/PluginHost';
 export type { ICEPlugin, ICEPluginTool, ICERenderHook, ICERenderFrame } from './plugin/PluginHost';
 export { default as Serializer, SERIALIZATION_VERSION } from './persistence/Serializer';