@retikz/vanilla 0.3.0-alpha.5 → 0.3.0-beta.2

package/dist/es/builder/{isFigure.d.ts → is-figure.d.ts}

@@ -3,4 +3,4 @@ import { Figure } from '../figure';
 export declare const FIGURE_BRAND: unique symbol;
 /** 运行时判断一个值是不是 Figure（带 brand）；纯结构检查、零内部 import → 不与 mountSvg/Figure 形成运行时环 */
 export declare const isFigure: (value: unknown) => value is Figure;
-//# sourceMappingURL=isFigure.d.ts.map
+//# sourceMappingURL=is-figure.d.ts.map

package/dist/es/builder/is-figure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-figure.d.ts","sourceRoot":"","sources":["../../../src/builder/is-figure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,oGAAoG;AACpG,eAAO,MAAM,YAAY,EAAE,OAAO,MAA4C,CAAC;AAE/E,+EAA+E;AAC/E,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MACuD,CAAC"}

package/dist/es/builder/{isFigure.js → is-figure.js}

@@ -1,4 +1,4 @@
-//#region src/builder/isFigure.ts
+//#region src/builder/is-figure.ts
 /** Figure 品牌标记（Symbol.for 跨包/重复 import 仍同一）；标准 mountSvg/renderToSvgString 用它区分 Figure 与 IR/Scene */
 var FIGURE_BRAND = Symbol.for("retikz.vanilla.figure");
 /** 运行时判断一个值是不是 Figure（带 brand）；纯结构检查、零内部 import → 不与 mountSvg/Figure 形成运行时环 */

package/dist/es/builder/scope.d.ts

@@ -11,7 +11,7 @@ export type ScopeBuilder = {
     node: (...args: Parameters<typeof node>) => ScopeBuilder;
     draw: (...args: Parameters<typeof draw>) => ScopeBuilder;
     coordinate: (...args: Parameters<typeof coordinate>) => ScopeBuilder;
-    scope: (config: ScopeConfig, build: (s: ScopeBuilder) => void) => ScopeBuilder;
+    scope: (config: ScopeConfig, arg: Array<Child> | ((s: ScopeBuilder) => void)) => ScopeBuilder;
 };
 /**
  * 构造一个 scope IR 子节点（分组容器 + 样式默认 + transforms）

package/dist/es/builder/scope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../src/builder/scope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAElD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,OAAO,IAAI,CAAC,KAAK,YAAY,CAAC;IACzD,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,OAAO,IAAI,CAAC,KAAK,YAAY,CAAC;IACzD,UAAU,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,KAAK,YAAY,CAAC;IACrE,KAAK,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,KAAK,YAAY,CAAC;CAChF,CAAC;AAwBF;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAAI,QAAQ,WAAW,EAAE,KAAK,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,CAAC,KAAG,KAS5F,CAAC"}
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../src/builder/scope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAElD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,OAAO,IAAI,CAAC,KAAK,YAAY,CAAC;IACzD,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,OAAO,IAAI,CAAC,KAAK,YAAY,CAAC;IACzD,UAAU,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,KAAK,YAAY,CAAC;IACrE,KAAK,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,CAAC,KAAK,YAAY,CAAC;CAC/F,CAAC;AAwBF;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAAI,QAAQ,WAAW,EAAE,KAAK,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,CAAC,KAAG,KAS5F,CAAC"}

package/dist/es/builder/scope.js

@@ -16,8 +16,8 @@ var createScopeBuilder = (sink) => {
 			sink.push(coordinate(...args));
 			return self;
 		},
-		scope(config, build) {
-			sink.push(scope(config, build));
+		scope(config, arg) {
+			sink.push(scope(config, arg));
 			return self;
 		}
 	};

package/dist/es/builder/types.d.ts

@@ -1,4 +1,4 @@
-import { CompileOptions, IRChild, IRCoordinate, IRNode, IRPath, IRScope, IRViewBox, WayDSL } from '@retikz/core';
+import { CompileOptions, IRAnimationTrack, IRChild, IRCoordinate, IRNode, IRPath, IRScope, IRViewBox, WayDSL } from '@retikz/core';
 /** builder 函数返回的 IR 子节点（node / draw / coordinate / scope 的产物） */
 export type Child = IRChild;
 /** node 的 config：从 IRNode 派生，剔除判别符 type 与提为 positional 的 id */
@@ -11,16 +11,29 @@ export type CoordinateConfig = Omit<IRCoordinate, 'type' | 'id'>;
 export type ScopeConfig = Omit<IRScope, 'type' | 'children'>;
 /** draw 的 way：直接复用 core 的 way DSL 全集（id 串 / 坐标 / Cycle / 折角 / 相对 / 曲线 / 弧 …） */
 export type Way = WayDSL;
+/**
+ * figure 根级级联样式默认（与 React `<Layout>` 顶层样式 props 对齐）
+ * @description 取 `IRScope` 的级联样式通道（graphic state + 四通道 every-X），**不含**容器 / 命名空间 / 变换 /
+ *   屏障 / 栈序 / 裁剪字段（那些挂在 figure 根上语义易混）。组 IR 时若任一字段携带样式指令，把根 children 包进
+ *   一层合成根 `<Scope>`，等价于用户手写一层根 scope；全缺省时不包，IR 形态逐字保持。
+ */
+export type FigureRootStyle = Pick<IRScope, 'color' | 'stroke' | 'fill' | 'strokeWidth' | 'opacity' | 'fillOpacity' | 'drawOpacity' | 'nodeDefault' | 'pathDefault' | 'labelDefault' | 'arrowDefault'>;
+/** {@link FigureRootStyle} 的字段表——`figure.ts` 组 IR 时拣根样式 + 从 render options 剔除（IR-only 字段不下发） */
+export declare const FIGURE_ROOT_STYLE_FIELDS: readonly ["color", "stroke", "fill", "strokeWidth", "opacity", "fillOpacity", "drawOpacity", "nodeDefault", "pathDefault", "labelDefault", "arrowDefault"];
 /**
  * figure 的 config
- * @description `viewBox` → IR.viewBox（内容坐标系）；`width`/`height` → 根 `<svg>` 显示尺寸（adapter 职责）；
- *   `idPrefix` → SVG 资源 id 前缀；其余（measureText / shapes / arrows / patterns / pathGenerators /
- *   padding / precision / nodeDistance / onWarn）派生自 core `CompileOptions`、原样喂 compileToScene。
+ * @description `viewBox` → IR.viewBox（内容坐标系）；`animations` → IR 根 `animations`（镜头时间轴，配 cameraTo
+ *   preset）；`width`/`height` → 根 `<svg>` 显示尺寸（adapter 职责）；`idPrefix` → SVG 资源 id 前缀；根级级联样式
+ *   （color / nodeDefault / pathDefault / labelDefault / arrowDefault 等）按需包合成根 `<Scope>`；其余（measureText /
+ *   shapes / arrows / patterns / pathGenerators / padding / precision / nodeDistance / onWarn）派生自 core
+ *   `CompileOptions`、原样喂 compileToScene。
  */
 export type FigureConfig = {
     width?: number;
     height?: number;
     viewBox?: IRViewBox;
     idPrefix?: string;
-} & CompileOptions;
+    /** scene 根（镜头）时间轴动画 tracks（`viewBox` property，配 `cameraTo()` preset）；注入 IR 根 `animations` */
+    animations?: Array<IRAnimationTrack>;
+} & FigureRootStyle & CompileOptions;
 //# sourceMappingURL=types.d.ts.map

package/dist/es/builder/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builder/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,OAAO,EACP,YAAY,EACZ,MAAM,EACN,MAAM,EACN,OAAO,EACP,SAAS,EACT,MAAM,EACP,MAAM,cAAc,CAAC;AAEtB,iEAAiE;AACjE,MAAM,MAAM,KAAK,GAAG,OAAO,CAAC;AAE5B,+DAA+D;AAC/D,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;AAErD,mEAAmE;AACnE,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC;AAE3D,qFAAqF;AACrF,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;AAEjE,8EAA8E;AAC9E,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC;AAE7D,gFAAgF;AAChF,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC;AAEzB;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,cAAc,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builder/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,OAAO,EACP,YAAY,EACZ,MAAM,EACN,MAAM,EACN,OAAO,EACP,SAAS,EACT,MAAM,EACP,MAAM,cAAc,CAAC;AAEtB,iEAAiE;AACjE,MAAM,MAAM,KAAK,GAAG,OAAO,CAAC;AAE5B,+DAA+D;AAC/D,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;AAErD,mEAAmE;AACnE,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC;AAE3D,qFAAqF;AACrF,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;AAEjE,8EAA8E;AAC9E,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC;AAE7D,gFAAgF;AAChF,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC;AAEzB;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,CAChC,OAAO,EACL,OAAO,GACP,QAAQ,GACR,MAAM,GACN,aAAa,GACb,SAAS,GACT,aAAa,GACb,aAAa,GACb,aAAa,GACb,aAAa,GACb,cAAc,GACd,cAAc,CACjB,CAAC;AAEF,gGAAgG;AAChG,eAAO,MAAM,wBAAwB,4JAYoB,CAAC;AAE1D;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6FAA6F;IAC7F,UAAU,CAAC,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;CACtC,GAAG,eAAe,GACjB,cAAc,CAAC"}

package/dist/es/builder/types.js

@@ -0,0 +1,17 @@
+//#region src/builder/types.ts
+/** {@link FigureRootStyle} 的字段表——`figure.ts` 组 IR 时拣根样式 + 从 render options 剔除（IR-only 字段不下发） */
+var FIGURE_ROOT_STYLE_FIELDS = [
+	"color",
+	"stroke",
+	"fill",
+	"strokeWidth",
+	"opacity",
+	"fillOpacity",
+	"drawOpacity",
+	"nodeDefault",
+	"pathDefault",
+	"labelDefault",
+	"arrowDefault"
+];
+//#endregion
+export { FIGURE_ROOT_STYLE_FIELDS };

package/dist/es/constants.d.ts

@@ -0,0 +1,3 @@
+/** 默认资源 id 前缀（确定性）；多实例同页须经 `options.idPrefix` 显式区分。SSR(`renderToSvgString`) 与 mount(`mountSvg`) 共用同一默认，避免两处漂移导致资源 id 失配。 */
+export declare const DEFAULT_ID_PREFIX = "r";
+//# sourceMappingURL=constants.d.ts.map

package/dist/es/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA,4HAA4H;AAC5H,eAAO,MAAM,iBAAiB,MAAM,CAAC"}

package/dist/es/figure.d.ts

@@ -1,25 +1,27 @@
 import { IR } from '@retikz/core';
 import { RenderOptions } from '@retikz/render/canvas';
-import { FIGURE_BRAND } from './builder/isFigure';
+import { FIGURE_BRAND } from './builder/is-figure';
 import { node } from './builder/node';
 import { ScopeBuilder } from './builder/scope';
 import { Child, CoordinateConfig, DrawConfig, FigureConfig, ScopeConfig, Way } from './builder/types';
-import { MountOptions, RenderToStringOptions, VanillaView } from './types';
+import { CanvasView, MountCanvasOptions, MountOptions, RenderToStringOptions, VanillaView } from './types';
 /**
  * 命令式 builder 的装配产物 —— 唯一返回类型
  * @description hyperscript（`figure(config, children)`）与 fluent（`figure(config).node(...)`）都产它、可混用、`.ir` 一致。
- *   `.mount`/`.toSvgString`/`.toCanvas` 把 `this.ir`（IR，非 Figure）交底层 renderer；fluent 方法往内部 children 追加、链式返回 this。
+ *   `.mount`/`.mountCanvas`（交互式挂载）/`.toSvgString`/`.toCanvas`（一次性产出）把 `this.ir`（IR，非 Figure）交底层
+ *   renderer；fluent 方法往内部 children 追加、链式返回 this。
  */
 export type Figure = {
     readonly [FIGURE_BRAND]: true;
     readonly ir: IR;
     mount: (container: Element, options?: MountOptions) => VanillaView;
+    mountCanvas: (container: Element, options?: MountCanvasOptions) => CanvasView;
     toSvgString: (options?: RenderToStringOptions) => string;
     toCanvas: (canvas: HTMLCanvasElement, options?: RenderOptions) => void;
     node: (...args: Parameters<typeof node>) => Figure;
     draw: (way: Way, config?: DrawConfig) => Figure;
     coordinate: (id: string, config: CoordinateConfig) => Figure;
-    scope: (config: ScopeConfig, build: (s: ScopeBuilder) => void) => Figure;
+    scope: (config: ScopeConfig, arg: Array<Child> | ((s: ScopeBuilder) => void)) => Figure;
 };
 /** figure() 的内部入口：装配 Figure（持 config + children，方法闭包其上） */
 export declare const createFigure: (config: FigureConfig, children: Array<Child>) => Figure;

package/dist/es/figure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"figure.d.ts","sourceRoot":"","sources":["../../src/figure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG3D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAI3G,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEhF;;;;GAIG;AACH,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC;IAC9B,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;IAChB,KAAK,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,WAAW,CAAC;IACnE,WAAW,EAAE,CAAC,OAAO,CAAC,EAAE,qBAAqB,KAAK,MAAM,CAAC;IACzD,QAAQ,EAAE,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,aAAa,KAAK,IAAI,CAAC;IACvE,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,OAAO,IAAI,CAAC,KAAK,MAAM,CAAC;IACnD,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,UAAU,KAAK,MAAM,CAAC;IAChD,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,KAAK,MAAM,CAAC;IAC7D,KAAK,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,KAAK,MAAM,CAAC;CAC1E,CAAC;AAEF,2DAA2D;AAC3D,eAAO,MAAM,YAAY,GAAI,QAAQ,YAAY,EAAE,UAAU,KAAK,CAAC,KAAK,CAAC,KAAG,MAoD3E,CAAC"}
+{"version":3,"file":"figure.d.ts","sourceRoot":"","sources":["../../src/figure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG3D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,OAAO,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,YAAY,EAAmB,WAAW,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAK5H,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,YAAY,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEhH;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC;IAC9B,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;IAChB,KAAK,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,WAAW,CAAC;IACnE,WAAW,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,kBAAkB,KAAK,UAAU,CAAC;IAC9E,WAAW,EAAE,CAAC,OAAO,CAAC,EAAE,qBAAqB,KAAK,MAAM,CAAC;IACzD,QAAQ,EAAE,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,aAAa,KAAK,IAAI,CAAC;IACvE,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,OAAO,IAAI,CAAC,KAAK,MAAM,CAAC;IACnD,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,UAAU,KAAK,MAAM,CAAC;IAChD,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,KAAK,MAAM,CAAC;IAC7D,KAAK,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,CAAC,KAAK,MAAM,CAAC;CACzF,CAAC;AAoBF,2DAA2D;AAC3D,eAAO,MAAM,YAAY,GAAI,QAAQ,YAAY,EAAE,UAAU,KAAK,CAAC,KAAK,CAAC,KAAG,MAoE3E,CAAC"}

package/dist/es/figure.js

@@ -1,37 +1,69 @@
-import { FIGURE_BRAND } from "./builder/isFigure.js";
-import { toScene } from "./toScene.js";
-import { renderToSvgString } from "./renderToSvgString.js";
-import { mountSvg } from "./mountSvg.js";
+import { FIGURE_BRAND } from "./builder/is-figure.js";
+import { toScene } from "./to-scene.js";
+import { renderToSvgString } from "./render-to-svg-string.js";
+import { mountSvg } from "./mount-svg.js";
+import { mountCanvas } from "./mount-canvas.js";
 import { coordinate } from "./builder/coordinate.js";
 import { draw } from "./builder/draw.js";
 import { node } from "./builder/node.js";
 import { scope } from "./builder/scope.js";
+import { FIGURE_ROOT_STYLE_FIELDS } from "./builder/types.js";
 import { renderToCanvas } from "@retikz/render/canvas";
 //#region src/figure.ts
+/**
+* 拣出真正携带样式指令的根样式字段
+* @description 在「取 defined」基础上剔除空对象的四通道 default（`nodeDefault: {}` 等）——空 default 无样式指令，
+*   留着只会让 figure 无谓包一层空合成根 `<Scope>`、改变 IR / Scene 拓扑却无视觉差异。标量通道的 falsy-但-defined
+*   值（`strokeWidth: 0` / `opacity: 0`）是有意义样式、保留（镜像 react `pickScopeStyle`）。
+*/
+var pickRootStyle = (config) => {
+	const picked = {};
+	for (const key of FIGURE_ROOT_STYLE_FIELDS) {
+		const value = config[key];
+		if (value === void 0) continue;
+		if (typeof value === "object" && Object.keys(value).length === 0) continue;
+		Object.assign(picked, { [key]: value });
+	}
+	return picked;
+};
 /** figure() 的内部入口：装配 Figure（持 config + children，方法闭包其上） */
 var createFigure = (config, children) => {
-	/** call-site options 覆盖 figure 存的 config（call-site wins）：viewBox 已并进 ir，其余（width/height/idPrefix + 全套 CompileOptions）全透传 */
+	/**
+	* call-site options 覆盖 figure 存的 config（call-site wins）：viewBox / animations / 根样式已并进 ir，
+	* 这些 IR-only 字段从下发的 render options 剔除；其余（width/height/idPrefix + 全套 CompileOptions）全透传。
+	*/
 	const renderOptions = (callSite) => {
 		const merged = {
 			...config,
 			...callSite
 		};
 		delete merged.viewBox;
+		delete merged.animations;
+		for (const key of FIGURE_ROOT_STYLE_FIELDS) delete merged[key];
 		return merged;
 	};
 	const fig = {
 		[FIGURE_BRAND]: true,
 		get ir() {
+			const rootStyle = pickRootStyle(config);
 			return {
 				version: 1,
 				type: "scene",
-				children,
-				...config.viewBox ? { viewBox: config.viewBox } : {}
+				children: Object.keys(rootStyle).length > 0 ? [{
+					type: "scope",
+					...rootStyle,
+					children
+				}] : children,
+				...config.viewBox ? { viewBox: config.viewBox } : {},
+				...config.animations ? { animations: config.animations } : {}
 			};
 		},
 		mount(container, options) {
 			return mountSvg(container, fig.ir, renderOptions(options));
 		},
+		mountCanvas(container, options) {
+			return mountCanvas(container, fig.ir, renderOptions(options));
+		},
 		toSvgString(options) {
 			return renderToSvgString(fig.ir, renderOptions(options));
 		},
@@ -41,6 +73,8 @@ var createFigure = (config, children) => {
 			delete compile.idPrefix;
 			delete compile.width;
 			delete compile.height;
+			delete compile.animations;
+			for (const key of FIGURE_ROOT_STYLE_FIELDS) delete compile[key];
 			renderToCanvas(canvas, toScene(fig.ir, compile), options ?? {});
 		},
 		node(...args) {
@@ -55,8 +89,8 @@ var createFigure = (config, children) => {
 			children.push(coordinate(id, coordConfig));
 			return fig;
 		},
-		scope(scopeConfig, build) {
-			children.push(scope(scopeConfig, build));
+		scope(scopeConfig, arg) {
+			children.push(scope(scopeConfig, arg));
 			return fig;
 		}
 	};

package/dist/es/index.d.ts

@@ -6,13 +6,19 @@
  * `figure`/`node`/`draw`/`coordinate`/`scope` 是命令式 builder：用具名图元 + 自定义 shape 构图、产同一份 IR。
  * 模块顶层不触碰任何 DOM 全局——`import` 在纯 Node 下安全。
  */
-export { renderToSvgString } from './renderToSvgString';
-export { mountSvg } from './mountSvg';
+export { renderToSvgString } from './render-to-svg-string';
+export { mountSvg } from './mount-svg';
 export { hydrate } from './hydrate';
-export { mountCanvas } from './mountCanvas';
-export type { RetikzEventName, HydrationHandlers, HydrationHandler, HydrationContext, HydrationAnimationControls, HydrationGeometry, } from '@retikz/render/hydration';
+export { mountCanvas } from './mount-canvas';
+export type { RetikzEventValue, HydrationHandlers, HydrationHandler, HydrationContext, HydrationAnimationControls, HydrationGeometry, } from '@retikz/render/hydration';
 export { fadeIn, drawOn, scaleIn, grow, growUp, slideIn, colorShift, cameraTo, pulse, spin, loop, flash, blink, wiggle, stagger, } from '@retikz/core';
 export type { AnimationPresetOptions, ScaleInOptions, GrowUpOptions, SlideInOptions, ColorShiftOptions, CameraToOptions, PulseOptions, SpinOptions, LoopOptions, FlashOptions, BlinkOptions, WiggleOptions, } from '@retikz/core';
+export { DrawWay } from '@retikz/core';
+export type { WayItem, WayDSL, WayCycle, WayVia, WayRelativeItem, WayLabel, WayLabelOp, } from '@retikz/core';
+export type { IRNodeTarget, IRAnchorRef } from '@retikz/core';
+export { defineArrow, definePattern, definePathGenerator } from '@retikz/core';
+export type { ArrowDefinition, ArrowEmitContext, PatternDefinition, PatternEmitContext, MarkerPrimitive, MarkerFill, PathGeneratorDefinition, PathGeneratorContext, IRJsonObject, } from '@retikz/core';
+export type { AnimationPropertyDefinition, AnimationPropertyRegistry, CubicBezier, EasingFn, EasingRegistry, } from '@retikz/render/animation';
 export { figure } from './builder/figure';
 export { node } from './builder/node';
 export { draw } from './builder/draw';
@@ -20,6 +26,6 @@ export { coordinate } from './builder/coordinate';
 export { scope } from './builder/scope';
 export type { Figure } from './figure';
 export type { ScopeBuilder } from './builder/scope';
-export type { Child, NodeConfig, DrawConfig, CoordinateConfig, ScopeConfig, FigureConfig, Way, } from './builder/types';
+export type { Child, NodeConfig, DrawConfig, CoordinateConfig, ScopeConfig, FigureConfig, FigureRootStyle, Way, } from './builder/types';
 export type { RenderInput, CommonOptions, MountOptions, RenderToStringOptions, VanillaView, CanvasView, MountCanvasOptions, HydrateOptions, HydrationHandle, ScenePoint, AnimationControls, } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/es/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,0BAA0B,EAC1B,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,MAAM,EACN,MAAM,EACN,OAAO,EACP,IAAI,EACJ,MAAM,EACN,OAAO,EACP,UAAU,EACV,QAAQ,EACR,KAAK,EACL,IAAI,EACJ,IAAI,EACJ,KAAK,EACL,KAAK,EACL,MAAM,EACN,OAAO,GACR,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,sBAAsB,EACtB,cAAc,EACd,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,WAAW,EACX,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EACV,KAAK,EACL,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,GAAG,GACJ,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,WAAW,EACX,aAAa,EACb,YAAY,EACZ,qBAAqB,EACrB,WAAW,EACX,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,UAAU,EACV,iBAAiB,GAClB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,0BAA0B,EAC1B,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,MAAM,EACN,MAAM,EACN,OAAO,EACP,IAAI,EACJ,MAAM,EACN,OAAO,EACP,UAAU,EACV,QAAQ,EACR,KAAK,EACL,IAAI,EACJ,IAAI,EACJ,KAAK,EACL,KAAK,EACL,MAAM,EACN,OAAO,GACR,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,sBAAsB,EACtB,cAAc,EACd,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,WAAW,EACX,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,YAAY,EACV,OAAO,EACP,MAAM,EACN,QAAQ,EACR,MAAM,EACN,eAAe,EACf,QAAQ,EACR,UAAU,GACX,MAAM,cAAc,CAAC;AAEtB,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE9D,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAC/E,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,UAAU,EACV,uBAAuB,EACvB,oBAAoB,EACpB,YAAY,GACb,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,2BAA2B,EAC3B,yBAAyB,EACzB,WAAW,EACX,QAAQ,EACR,cAAc,GACf,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EACV,KAAK,EACL,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,eAAe,EACf,GAAG,GACJ,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,WAAW,EACX,aAAa,EACb,YAAY,EACZ,qBAAqB,EACrB,WAAW,EACX,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,UAAU,EACV,iBAAiB,GAClB,MAAM,SAAS,CAAC"}

package/dist/es/index.js

@@ -1,11 +1,11 @@
-import { renderToSvgString } from "./renderToSvgString.js";
-import { mountSvg } from "./mountSvg.js";
+import { renderToSvgString } from "./render-to-svg-string.js";
+import { mountSvg } from "./mount-svg.js";
 import { hydrate } from "./hydrate.js";
-import { mountCanvas } from "./mountCanvas.js";
+import { mountCanvas } from "./mount-canvas.js";
 import { coordinate } from "./builder/coordinate.js";
 import { draw } from "./builder/draw.js";
 import { node } from "./builder/node.js";
 import { scope } from "./builder/scope.js";
 import { figure } from "./builder/figure.js";
-import { blink, cameraTo, colorShift, drawOn, fadeIn, flash, grow, growUp, loop, pulse, scaleIn, slideIn, spin, stagger, wiggle } from "@retikz/core";
-export { blink, cameraTo, colorShift, coordinate, draw, drawOn, fadeIn, figure, flash, grow, growUp, hydrate, loop, mountCanvas, mountSvg, node, pulse, renderToSvgString, scaleIn, scope, slideIn, spin, stagger, wiggle };
+import { DrawWay, blink, cameraTo, colorShift, defineArrow, definePathGenerator, definePattern, drawOn, fadeIn, flash, grow, growUp, loop, pulse, scaleIn, slideIn, spin, stagger, wiggle } from "@retikz/core";
+export { DrawWay, blink, cameraTo, colorShift, coordinate, defineArrow, definePathGenerator, definePattern, draw, drawOn, fadeIn, figure, flash, grow, growUp, hydrate, loop, mountCanvas, mountSvg, node, pulse, renderToSvgString, scaleIn, scope, slideIn, spin, stagger, wiggle };

package/dist/{lib/mountCanvas.d.ts → es/mount-canvas.d.ts}

@@ -1,10 +1,11 @@
 import { CanvasView, MountCanvasOptions, RenderInput } from './types';
 /**
  * 把 IR / Scene / Figure 挂成真实 `<canvas>` DOM（无框架浏览器 runtime，对齐 `mountSvg`）
- * @description 收 IR 时 `toScene` compile、收 Scene 直用、收 Figure 解 `figure.ir`。位图按「名义显示尺寸」
+ * @description 收 `Figure` 时 delegate 给 `figure.mountCanvas`（与 mountSvg→`figure.mount` 对称）。收 IR 时
+ *   `toScene` compile、收 Scene 直用。位图按「名义显示尺寸」
  *   `width`/`height`（均为有限数值时）× dpr 开、否则回退内容边界；`renderToCanvas` 再把 Scene 内容 meet-fit
  *   进去（镜像 SVG `preserveAspectRatio=meet` + CanvasHost）。返回的 `CanvasView` 暴露 `hydrate`（hitTest 定位）
  *   与 `clientToScene`（逆 meet-fit 坐标映射）。DOM 仅在调用时惰性触碰，`import` 本模块不碰 DOM——守 SSR 导入安全。
  */
 export declare const mountCanvas: (container: Element, input: RenderInput, options?: MountCanvasOptions) => CanvasView;
-//# sourceMappingURL=mountCanvas.d.ts.map
+//# sourceMappingURL=mount-canvas.d.ts.map

package/dist/es/mount-canvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-canvas.d.ts","sourceRoot":"","sources":["../../src/mount-canvas.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,UAAU,EAAkB,kBAAkB,EAAE,WAAW,EAAc,MAAM,SAAS,CAAC;AASvG;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GACtB,WAAW,OAAO,EAClB,OAAO,WAAW,EAClB,UAAS,kBAAuB,KAC/B,UA4PF,CAAC"}

package/dist/es/{mountCanvas.js → mount-canvas.js}

@@ -1,9 +1,9 @@
-import { isFigure } from "./builder/isFigure.js";
-import { toScene } from "./toScene.js";
+import { isFigure } from "./builder/is-figure.js";
+import { toScene } from "./to-scene.js";
 import { createClock, createIdClockRegistry, prefersReducedMotion, sceneAnimationDurationMs, sceneHasAnimations, sceneHasAutoplayTrigger } from "@retikz/render/animation";
-import { createCanvasIdAnimationControls, createHydrationController, geometryOf, metaOf } from "@retikz/render/hydration";
+import { collectCanvasVisibleAnimationIds, createCanvasIdAnimationControls, createContextBuilder, createHydrationController, isCanvasAnimationIdVisible, withCanvasAnimationEventHandlers } from "@retikz/render/hydration";
 import { hitTest, renderToCanvas } from "@retikz/render/canvas";
-//#region src/mountCanvas.ts
+//#region src/mount-canvas.ts
 /** 设备像素比：取有限正数、否则回退 1（镜像 react CanvasHost） */
 var resolveDevicePixelRatio = (override) => {
 	if (typeof override === "number" && Number.isFinite(override) && override > 0) return override;
@@ -12,19 +12,24 @@ var resolveDevicePixelRatio = (override) => {
 };
 /**
 * 把 IR / Scene / Figure 挂成真实 `<canvas>` DOM（无框架浏览器 runtime，对齐 `mountSvg`）
-* @description 收 IR 时 `toScene` compile、收 Scene 直用、收 Figure 解 `figure.ir`。位图按「名义显示尺寸」
+* @description 收 `Figure` 时 delegate 给 `figure.mountCanvas`（与 mountSvg→`figure.mount` 对称）。收 IR 时
+*   `toScene` compile、收 Scene 直用。位图按「名义显示尺寸」
 *   `width`/`height`（均为有限数值时）× dpr 开、否则回退内容边界；`renderToCanvas` 再把 Scene 内容 meet-fit
 *   进去（镜像 SVG `preserveAspectRatio=meet` + CanvasHost）。返回的 `CanvasView` 暴露 `hydrate`（hitTest 定位）
 *   与 `clientToScene`（逆 meet-fit 坐标映射）。DOM 仅在调用时惰性触碰，`import` 本模块不碰 DOM——守 SSR 导入安全。
 */
 var mountCanvas = (container, input, options = {}) => {
+	if (isFigure(input)) return input.mountCanvas(container, options);
 	if (typeof Element === "undefined" || !(container instanceof Element)) throw new Error("mountCanvas: container must be a DOM Element.");
 	const canvas = document.createElement("canvas");
 	const ratio = resolveDevicePixelRatio(options.devicePixelRatio);
 	const animate = options.animate !== false && !prefersReducedMotion();
 	let clock;
 	const registry = createIdClockRegistry();
+	let visibleActivated = /* @__PURE__ */ new Set();
+	let visibleTeardown;
 	let currentScene;
+	const liveHydrations = /* @__PURE__ */ new Set();
 	/** 把全局帧时刻折算成单个 prim 的动画解析（per-id）：stop→渲染 base；否则按有效时刻 + 是否含非自动播 track */
 	const resolvePrim = (id, globalTime) => id !== void 0 && registry.isStopped(id) ? { mode: "skip" } : {
 		mode: "at",
@@ -42,6 +47,49 @@ var mountCanvas = (container, input, options = {}) => {
 			resolvePrimAnimation: (id) => resolvePrim(id, time)
 		});
 	};
+	const ensureClockPlaying = () => {
+		clock?.play();
+	};
+	/** Canvas visible trigger：按 canvas client rect 与 id 聚合 bbox 相交激活一次 */
+	const activateVisibleTracks = () => {
+		const ids = collectCanvasVisibleAnimationIds(currentScene);
+		if (ids.size === 0) return;
+		let changed = false;
+		for (const id of ids) {
+			if (visibleActivated.has(id)) continue;
+			if (!isCanvasAnimationIdVisible(canvas, currentScene, id)) continue;
+			registry.restart(id, clock?.time ?? 0);
+			visibleActivated.add(id);
+			changed = true;
+		}
+		if (!changed) return;
+		ensureClockPlaying();
+		renderFrame();
+	};
+	const resetVisibleBridge = () => {
+		visibleActivated = /* @__PURE__ */ new Set();
+		visibleTeardown?.();
+		visibleTeardown = void 0;
+		if (!animate || !sceneHasAnimations(currentScene)) return;
+		if (collectCanvasVisibleAnimationIds(currentScene).size === 0 || typeof window === "undefined") return;
+		let scheduledRaf;
+		const runScheduled = () => {
+			scheduledRaf = void 0;
+			activateVisibleTracks();
+		};
+		const schedule = () => {
+			if (scheduledRaf !== void 0) return;
+			scheduledRaf = window.requestAnimationFrame(runScheduled);
+		};
+		window.addEventListener("scroll", schedule, true);
+		window.addEventListener("resize", schedule);
+		schedule();
+		visibleTeardown = () => {
+			window.removeEventListener("scroll", schedule, true);
+			window.removeEventListener("resize", schedule);
+			if (scheduledRaf !== void 0) window.cancelAnimationFrame(scheduledRaf);
+		};
+	};
 	const renderInto = (next) => {
 		if (isFigure(next)) throw new Error("mountCanvas: view.update does not accept a Figure; pass figure.ir instead.");
 		const scene = toScene(next, options);
@@ -54,6 +102,15 @@ var mountCanvas = (container, input, options = {}) => {
 		if (options.width !== void 0) canvas.style.width = `${options.width}px`;
 		if (options.height !== void 0) canvas.style.height = `${options.height}px`;
 		canvas.style.objectFit = "contain";
+		if (options.snapshotAt !== void 0) {
+			renderToCanvas(canvas, scene, {
+				devicePixelRatio: ratio,
+				time: options.snapshotAt,
+				easings: options.easings,
+				animationProperties: options.animationProperties
+			});
+			return;
+		}
 		renderToCanvas(canvas, scene, { devicePixelRatio: ratio });
 		clock?.dispose();
 		clock = void 0;
@@ -70,8 +127,9 @@ var mountCanvas = (container, input, options = {}) => {
 			});
 			if (sceneHasAutoplayTrigger(scene)) clock.play();
 		}
+		resetVisibleBridge();
 	};
-	renderInto(isFigure(input) ? input.ir : input);
+	renderInto(input);
 	container.appendChild(canvas);
 	/**
 	* 把指针的 client 像素坐标逆 meet-fit 映射成 Scene user units
@@ -109,38 +167,57 @@ var mountCanvas = (container, input, options = {}) => {
 			context2d?.setTransform(1, 0, 0, 1, 0, 0);
 			return hitTest(currentScene, scenePoint, { context2d });
 		};
-		const buildContext = (event, id) => {
-			const mouse = event;
-			return {
-				id,
-				meta: metaOf(currentScene, id),
-				renderer: "canvas",
-				element: null,
-				root: canvas,
-				point: typeof mouse.clientX === "number" ? clientToScene(mouse.clientX, mouse.clientY) : null,
-				geometry: geometryOf(currentScene, id),
-				animation: createCanvasIdAnimationControls({
-					registry,
-					clockTime: () => clock?.time ?? 0,
-					ensurePlaying: () => clock?.play(),
-					renderFrame,
-					defaultId: id
-				}),
-				scene: currentScene
-			};
+		const buildContext = createContextBuilder({
+			renderer: "canvas",
+			root: canvas,
+			scene: () => currentScene,
+			resolveElement: () => null,
+			resolvePoint: (event) => {
+				const mouse = event;
+				return typeof mouse.clientX === "number" ? clientToScene(mouse.clientX, mouse.clientY) : null;
+			},
+			makeAnimation: (id) => createCanvasIdAnimationControls({
+				registry,
+				clockTime: () => clock?.time ?? 0,
+				ensurePlaying: () => clock?.play(),
+				renderFrame,
+				defaultId: id
+			})
+		});
+		const userHandlers = hydrateOptions.handlers;
+		const bind = () => createHydrationController(canvas, withCanvasAnimationEventHandlers(currentScene, userHandlers), locate, buildContext);
+		let controller = bind();
+		const live = {
+			rebind: () => {
+				controller.dispose();
+				controller = bind();
+			},
+			unbind: () => controller.dispose()
 		};
-		return { dispose: createHydrationController(canvas, hydrateOptions.handlers, locate, buildContext).dispose };
+		liveHydrations.add(live);
+		return { dispose: () => {
+			live.unbind();
+			liveHydrations.delete(live);
+		} };
+	};
+	/** update 换 scene 后按新 scene 重建存活水合的 onEvent 动画 handler 表（新增 / 移除的 onEvent track 即时反映） */
+	const rebindHydrations = () => {
+		for (const live of liveHydrations) live.rebind();
 	};
 	return {
 		root: canvas,
 		update(next) {
 			if (disposed) throw new Error("mountCanvas: view already disposed.");
 			renderInto(next);
+			rebindHydrations();
 		},
 		dispose() {
 			if (disposed) return;
 			disposed = true;
+			visibleTeardown?.();
 			clock?.dispose();
+			for (const live of liveHydrations) live.unbind();
+			liveHydrations.clear();
 			canvas.remove();
 		},
 		hydrate,

package/dist/es/{mountSvg.d.ts → mount-svg.d.ts}

@@ -7,4 +7,4 @@ import { MountOptions, RenderInput, VanillaView } from './types';
  *   原地重渲染、root 元素 identity 跨 update 不变、不失效。DOM 仅在调用时惰性触碰，`import` 本模块不碰 DOM——守 SSR 导入安全。
  */
 export declare const mountSvg: (container: Element, input: RenderInput, options?: MountOptions) => VanillaView;
-//# sourceMappingURL=mountSvg.d.ts.map
+//# sourceMappingURL=mount-svg.d.ts.map

package/dist/es/mount-svg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-svg.d.ts","sourceRoot":"","sources":["../../src/mount-svg.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAmC,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAIvG;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GAAI,WAAW,OAAO,EAAE,OAAO,WAAW,EAAE,UAAS,YAAiB,KAAG,WAkF7F,CAAC"}

package/dist/es/{mountSvg.js → mount-svg.js}

@@ -1,13 +1,11 @@
-import { isFigure } from "./builder/isFigure.js";
-import { toScene } from "./toScene.js";
-import { applyAttrs, svgNodeToDom } from "./svgNodeToDom.js";
+import { isFigure } from "./builder/is-figure.js";
+import { toScene } from "./to-scene.js";
+import { applyAttrs, svgNodeToDom } from "./svg-node-to-dom.js";
 import { buildSvgDocument } from "@retikz/render/svg";
 import { bindWaapiDescriptors, prefersReducedMotion, sceneHasAnimations } from "@retikz/render/animation";
-import { createHydrationController, createSvgAnimationControls, geometryOf, locateSvg, metaOf, resolvePointViaLayout, resolveSvgElement } from "@retikz/render/hydration";
-//#region src/mountSvg.ts
+import { createContextBuilder, createHydrationController, createSvgAnimationControls, locateSvg, resolvePointViaLayout, resolveSvgElement } from "@retikz/render/hydration";
+//#region src/mount-svg.ts
 var SVG_NS = "http://www.w3.org/2000/svg";
-/** 默认资源 id 前缀（确定性）；多实例同页须经 `options.idPrefix` 显式区分 */
-var DEFAULT_ID_PREFIX = "r";
 /**
 * 把 IR / Scene / Figure 挂成真实 SVG DOM（无框架浏览器 runtime）
 * @description 收 `Figure` 时 delegate 给 `figure.mount`（Figure 自持 config，call-site options 覆盖）。收
@@ -18,11 +16,12 @@ var DEFAULT_ID_PREFIX = "r";
 var mountSvg = (container, input, options = {}) => {
 	if (isFigure(input)) return input.mount(container, options);
 	if (typeof Element === "undefined" || !(container instanceof Element)) throw new Error("mountSvg: container must be a DOM Element.");
-	const idPrefix = options.idPrefix ?? DEFAULT_ID_PREFIX;
+	const idPrefix = options.idPrefix ?? "r";
 	const root = document.createElementNS(SVG_NS, "svg");
 	const animate = options.animate !== false && !prefersReducedMotion();
 	let animationControls;
 	let currentScene;
+	const liveHydrationDisposers = /* @__PURE__ */ new Set();
 	const renderInto = (next) => {
 		if (isFigure(next)) throw new Error("mountSvg: view.update does not accept a Figure; pass figure.ir instead.");
 		const scene = toScene(next, options);
@@ -51,18 +50,21 @@ var mountSvg = (container, input, options = {}) => {
 	*   `data-retikz-animation-owner` 双查 `getAnimations()` per-id 控制。
 	*/
 	const hydrate = (hydrateOptions) => {
-		const buildContext = (event, id) => ({
-			id,
-			meta: metaOf(currentScene, id),
+		const buildContext = createContextBuilder({
 			renderer: "svg",
-			element: resolveSvgElement(event),
 			root,
-			point: resolvePointViaLayout(root, currentScene.layout)(event),
-			geometry: geometryOf(currentScene, id),
-			animation: createSvgAnimationControls(root, id),
-			scene: currentScene
+			scene: () => currentScene,
+			resolveElement: resolveSvgElement,
+			resolvePoint: (event) => resolvePointViaLayout(root, currentScene.layout)(event),
+			makeAnimation: (id) => createSvgAnimationControls(root, id)
 		});
-		return { dispose: createHydrationController(root, hydrateOptions.handlers, locateSvg, buildContext).dispose };
+		const controller = createHydrationController(root, hydrateOptions.handlers, locateSvg, buildContext);
+		const dispose = () => {
+			controller.dispose();
+			liveHydrationDisposers.delete(dispose);
+		};
+		liveHydrationDisposers.add(dispose);
+		return { dispose };
 	};
 	let disposed = false;
 	return {
@@ -75,6 +77,7 @@ var mountSvg = (container, input, options = {}) => {
 		dispose() {
 			if (disposed) return;
 			disposed = true;
+			for (const disposeHydration of [...liveHydrationDisposers]) disposeHydration();
 			animationControls?.dispose();
 			root.remove();
 		},