@retikz/vanilla 0.3.0-alpha.4 → 0.3.0-beta.1

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/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

@@ -4,22 +4,24 @@ import { FIGURE_BRAND } from './builder/isFigure';
 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,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;AAK3G,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;AAEF,2DAA2D;AAC3D,eAAO,MAAM,YAAY,GAAI,QAAQ,YAAY,EAAE,UAAU,KAAK,CAAC,KAAK,CAAC,KAAG,MAwD3E,CAAC"}

package/dist/es/figure.js

@@ -2,6 +2,7 @@ import { FIGURE_BRAND } from "./builder/isFigure.js";
 import { toScene } from "./toScene.js";
 import { renderToSvgString } from "./renderToSvgString.js";
 import { mountSvg } from "./mountSvg.js";
+import { mountCanvas } from "./mountCanvas.js";
 import { coordinate } from "./builder/coordinate.js";
 import { draw } from "./builder/draw.js";
 import { node } from "./builder/node.js";
@@ -32,6 +33,9 @@ var createFigure = (config, children) => {
 		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));
 		},
@@ -55,8 +59,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/hydrate.d.ts

@@ -1,10 +1,16 @@
 import { HydrateOptions, HydrationHandle } from './types';
 /**
- * 把用户 handler 水合到容器内已挂的 `<svg>`（无框架 SVG 水合入口）
+ * 把用户 handler 水合到容器内已挂的 `<svg>`（SSR 后的独立 SVG 水合入口）
  * @description SSR / `mountSvg` 先渲染出含 `data-retikz-id` 的图，本入口再把 handler 绑回图元——不重建 DOM、
- *   不接管状态，只做「图元 id ↔ 用户函数」绑定。用 `@retikz/render/hydration` 的 `createHydrationController(root,
- *   handlers, locateSvg)` 在 `root` 上挂根级委托：事件经 `closest('[data-retikz-id]')` 反查图元 id，命中即触发
- *   对应 handler；`pointerEnter` / `pointerLeave` 由控制器经 `pointermove` + 命中 id 状态机合成。返回 `{ dispose }` 解绑。
+ *   不接管状态，只做「图元 id ↔ 用户函数」绑定。用 `createHydrationController(root, handlers, locateSvg, buildContext)`
+ *   在 `root` 上挂根级委托：事件经 `closest('[data-retikz-id]')` 反查图元 id，命中即以 `(event, context)` 触发对应
+ *   handler；`pointerEnter` / `pointerLeave` 由控制器经 `pointermove` + 命中 id 状态机合成。返回 `{ dispose }` 解绑。
+ *
+ *   **context 能力分两档**：传 `options.scene`（可经 `toScene(ir)` 得到）→ 富 context——`meta` / `geometry` 经 Scene 按 id
+ *   聚合查询、`point` 逆 meet-fit、`animation` 经 `data-retikz-id` / `data-retikz-animation-owner` 双查
+ *   `getAnimations()` per-id 控制；不传 → 最小 context——`id` + `element` + `root` + `renderer`，`point` 退 `getScreenCTM`
+ *   （浏览器有效、jsdom 为 null），`meta` / `geometry` / `scene` undefined、`animation` no-op。SSR 后要富 context 须把
+ *   `scene` 一并传入。
  */
 export declare const hydrate: (root: Element, options: HydrateOptions) => HydrationHandle;
 //# sourceMappingURL=hydrate.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../../src/hydrate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/D;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,OAAO,EAAE,SAAS,cAAc,KAAG,eAGhE,CAAC"}
+{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../../src/hydrate.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,OAAO,EAAE,SAAS,cAAc,KAAG,eAahE,CAAC"}

package/dist/es/hydrate.js

@@ -1,14 +1,30 @@
-import { createHydrationController, locateSvg } from "@retikz/render/hydration";
+import { createContextBuilder, createHydrationController, createSvgAnimationControls, locateSvg, noopAnimationControls, resolvePointViaLayout, resolveSvgElement, resolveSvgPointViaCtm } from "@retikz/render/hydration";
 //#region src/hydrate.ts
 /**
-* 把用户 handler 水合到容器内已挂的 `<svg>`（无框架 SVG 水合入口）
+* 把用户 handler 水合到容器内已挂的 `<svg>`（SSR 后的独立 SVG 水合入口）
 * @description SSR / `mountSvg` 先渲染出含 `data-retikz-id` 的图，本入口再把 handler 绑回图元——不重建 DOM、
-*   不接管状态，只做「图元 id ↔ 用户函数」绑定。用 `@retikz/render/hydration` 的 `createHydrationController(root,
-*   handlers, locateSvg)` 在 `root` 上挂根级委托：事件经 `closest('[data-retikz-id]')` 反查图元 id，命中即触发
-*   对应 handler；`pointerEnter` / `pointerLeave` 由控制器经 `pointermove` + 命中 id 状态机合成。返回 `{ dispose }` 解绑。
+*   不接管状态，只做「图元 id ↔ 用户函数」绑定。用 `createHydrationController(root, handlers, locateSvg, buildContext)`
+*   在 `root` 上挂根级委托：事件经 `closest('[data-retikz-id]')` 反查图元 id，命中即以 `(event, context)` 触发对应
+*   handler；`pointerEnter` / `pointerLeave` 由控制器经 `pointermove` + 命中 id 状态机合成。返回 `{ dispose }` 解绑。
+*
+*   **context 能力分两档**：传 `options.scene`（可经 `toScene(ir)` 得到）→ 富 context——`meta` / `geometry` 经 Scene 按 id
+*   聚合查询、`point` 逆 meet-fit、`animation` 经 `data-retikz-id` / `data-retikz-animation-owner` 双查
+*   `getAnimations()` per-id 控制；不传 → 最小 context——`id` + `element` + `root` + `renderer`，`point` 退 `getScreenCTM`
+*   （浏览器有效、jsdom 为 null），`meta` / `geometry` / `scene` undefined、`animation` no-op。SSR 后要富 context 须把
+*   `scene` 一并传入。
 */
 var hydrate = (root, options) => {
-	return { dispose: createHydrationController(root, options.handlers, locateSvg).dispose };
+	const renderer = options.renderer ?? "svg";
+	const scene = options.scene;
+	const buildContext = createContextBuilder({
+		renderer,
+		root,
+		scene,
+		resolveElement: resolveSvgElement,
+		resolvePoint: scene ? resolvePointViaLayout(root, scene.layout) : resolveSvgPointViaCtm(root),
+		makeAnimation: scene ? (id) => createSvgAnimationControls(root, id) : () => noopAnimationControls
+	});
+	return { dispose: createHydrationController(root, options.handlers, locateSvg, buildContext).dispose };
 };
 //#endregion
 export { hydrate };

package/dist/es/index.d.ts

@@ -10,6 +10,15 @@ export { renderToSvgString } from './renderToSvgString';
 export { mountSvg } from './mountSvg';
 export { hydrate } from './hydrate';
 export { mountCanvas } from './mountCanvas';
+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';
@@ -18,5 +27,5 @@ 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 { RenderInput, CommonOptions, MountOptions, RenderToStringOptions, VanillaView, CanvasView, MountCanvasOptions, HydrateOptions, HydrationHandle, ScenePoint, } from './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;AAC5C,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,GACX,MAAM,SAAS,CAAC"}
+{"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,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,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

@@ -7,4 +7,5 @@ import { draw } from "./builder/draw.js";
 import { node } from "./builder/node.js";
 import { scope } from "./builder/scope.js";
 import { figure } from "./builder/figure.js";
-export { coordinate, draw, figure, hydrate, mountCanvas, mountSvg, node, renderToSvgString, scope };
+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/es/mountCanvas.d.ts

@@ -1,7 +1,8 @@
 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 导入安全。

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

@@ -1 +1 @@
-{"version":3,"file":"mountCanvas.d.ts","sourceRoot":"","sources":["../../src/mountCanvas.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAkB,kBAAkB,EAAE,WAAW,EAAc,MAAM,SAAS,CAAC;AASvG;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GACtB,WAAW,OAAO,EAClB,OAAO,WAAW,EAClB,UAAS,kBAAuB,KAC/B,UAyFF,CAAC"}
+{"version":3,"file":"mountCanvas.d.ts","sourceRoot":"","sources":["../../src/mountCanvas.ts"],"names":[],"mappings":"AAaA,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,UA2MF,CAAC"}

package/dist/es/mountCanvas.js

@@ -1,6 +1,7 @@
 import { isFigure } from "./builder/isFigure.js";
 import { toScene } from "./toScene.js";
-import { createHydrationController } from "@retikz/render/hydration";
+import { createClock, createIdClockRegistry, prefersReducedMotion, sceneAnimationDurationMs, sceneHasAnimations, sceneHasAutoplayTrigger } from "@retikz/render/animation";
+import { collectCanvasVisibleAnimationIds, createCanvasIdAnimationControls, createContextBuilder, createHydrationController, isCanvasAnimationIdVisible, withCanvasAnimationEventHandlers } from "@retikz/render/hydration";
 import { hitTest, renderToCanvas } from "@retikz/render/canvas";
 //#region src/mountCanvas.ts
 /** 设备像素比：取有限正数、否则回退 1（镜像 react CanvasHost） */
@@ -11,16 +12,75 @@ 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;
+	/** 把全局帧时刻折算成单个 prim 的动画解析（per-id）：stop→渲染 base；否则按有效时刻 + 是否含非自动播 track */
+	const resolvePrim = (id, globalTime) => id !== void 0 && registry.isStopped(id) ? { mode: "skip" } : {
+		mode: "at",
+		time: registry.timeFor(id, globalTime),
+		includeNonAutoplay: registry.isActive(id)
+	};
+	/** 按当前时钟时刻 + per-id 登记表立即重绘一帧（per-id pause / stop 即时反映） */
+	const renderFrame = () => {
+		const time = clock?.time ?? 0;
+		renderToCanvas(canvas, currentScene, {
+			devicePixelRatio: ratio,
+			time,
+			easings: options.easings,
+			animationProperties: options.animationProperties,
+			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;
+		const schedule = () => activateVisibleTracks();
+		window.addEventListener("scroll", schedule, true);
+		window.addEventListener("resize", schedule);
+		const raf = window.requestAnimationFrame(schedule);
+		visibleTeardown = () => {
+			window.removeEventListener("scroll", schedule, true);
+			window.removeEventListener("resize", schedule);
+			window.cancelAnimationFrame(raf);
+		};
+	};
 	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);
@@ -34,8 +94,24 @@ var mountCanvas = (container, input, options = {}) => {
 		if (options.height !== void 0) canvas.style.height = `${options.height}px`;
 		canvas.style.objectFit = "contain";
 		renderToCanvas(canvas, scene, { devicePixelRatio: ratio });
+		clock?.dispose();
+		clock = void 0;
+		if (animate && sceneHasAnimations(scene)) {
+			clock = createClock({
+				durationMs: sceneAnimationDurationMs(scene),
+				onFrame: (time) => renderToCanvas(canvas, currentScene, {
+					devicePixelRatio: ratio,
+					time,
+					easings: options.easings,
+					animationProperties: options.animationProperties,
+					resolvePrimAnimation: (id) => resolvePrim(id, time)
+				})
+			});
+			if (sceneHasAutoplayTrigger(scene)) clock.play();
+		}
+		resetVisibleBridge();
 	};
-	renderInto(isFigure(input) ? input.ir : input);
+	renderInto(input);
 	container.appendChild(canvas);
 	/**
 	* 把指针的 client 像素坐标逆 meet-fit 映射成 Scene user units
@@ -68,11 +144,29 @@ var mountCanvas = (container, input, options = {}) => {
 	*/
 	const hydrate = (hydrateOptions) => {
 		const context2d = canvas.getContext("2d") ?? void 0;
-		return { dispose: createHydrationController(canvas, hydrateOptions.handlers, (event) => {
+		const locate = (event) => {
 			const scenePoint = clientToScene(event.clientX, event.clientY);
 			context2d?.setTransform(1, 0, 0, 1, 0, 0);
 			return hitTest(currentScene, scenePoint, { context2d });
-		}).dispose };
+		};
+		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
+			})
+		});
+		return { dispose: createHydrationController(canvas, withCanvasAnimationEventHandlers(currentScene, hydrateOptions.handlers), locate, buildContext).dispose };
 	};
 	return {
 		root: canvas,
@@ -83,10 +177,15 @@ var mountCanvas = (container, input, options = {}) => {
 		dispose() {
 			if (disposed) return;
 			disposed = true;
+			visibleTeardown?.();
+			clock?.dispose();
 			canvas.remove();
 		},
 		hydrate,
-		clientToScene
+		clientToScene,
+		get animation() {
+			return clock;
+		}
 	};
 };
 //#endregion

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

@@ -1 +1 @@
-{"version":3,"file":"mountSvg.d.ts","sourceRoot":"","sources":["../../src/mountSvg.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAMtE;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GAAI,WAAW,OAAO,EAAE,OAAO,WAAW,EAAE,UAAS,YAAiB,KAAG,WAwC7F,CAAC"}
+{"version":3,"file":"mountSvg.d.ts","sourceRoot":"","sources":["../../src/mountSvg.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,WAyE7F,CAAC"}

package/dist/es/mountSvg.js

@@ -2,10 +2,10 @@ import { isFigure } from "./builder/isFigure.js";
 import { toScene } from "./toScene.js";
 import { applyAttrs, svgNodeToDom } from "./svgNodeToDom.js";
 import { buildSvgDocument } from "@retikz/render/svg";
+import { bindWaapiDescriptors, prefersReducedMotion, sceneHasAnimations } from "@retikz/render/animation";
+import { createContextBuilder, createHydrationController, createSvgAnimationControls, locateSvg, resolvePointViaLayout, resolveSvgElement } from "@retikz/render/hydration";
 //#region src/mountSvg.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 覆盖）。收
@@ -16,20 +16,49 @@ 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 renderInto = (next) => {
 		if (isFigure(next)) throw new Error("mountSvg: view.update does not accept a Figure; pass figure.ir instead.");
-		const doc = buildSvgDocument(toScene(next, options), { idPrefix });
+		const scene = toScene(next, options);
+		currentScene = scene;
+		const doc = buildSvgDocument(scene, {
+			idPrefix,
+			animate,
+			snapshotAt: options.snapshotAt,
+			easings: options.easings
+		});
 		while (root.firstChild) root.removeChild(root.firstChild);
 		for (const attr of [...root.attributes]) root.removeAttribute(attr.name);
 		applyAttrs(root, doc);
 		if (options.width !== void 0) root.setAttribute("width", String(options.width));
 		if (options.height !== void 0) root.setAttribute("height", String(options.height));
 		for (const child of doc.children ?? []) root.appendChild(typeof child === "string" ? document.createTextNode(child) : svgNodeToDom(child));
+		animationControls?.dispose();
+		animationControls = animate && sceneHasAnimations(scene) ? bindWaapiDescriptors(root) : void 0;
 	};
 	renderInto(input);
 	container.appendChild(root);
+	/**
+	* 把 handler 绑到本 view 的 `<svg>`，handler 收 `(event, context)` 富上下文
+	* @description `buildContext` 读 live `currentScene`（`update` 后自动反映新图）：meta / geometry 经 Scene 按 id
+	*   聚合查询，element 经 `closest('[data-retikz-id]')`，point 逆 meet-fit，动画控制经 `data-retikz-id` /
+	*   `data-retikz-animation-owner` 双查 `getAnimations()` per-id 控制。
+	*/
+	const hydrate = (hydrateOptions) => {
+		const buildContext = createContextBuilder({
+			renderer: "svg",
+			root,
+			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 };
+	};
 	let disposed = false;
 	return {
 		root,
@@ -37,10 +66,15 @@ var mountSvg = (container, input, options = {}) => {
 			if (disposed) throw new Error("mountSvg: view already disposed.");
 			renderInto(next);
 		},
+		hydrate,
 		dispose() {
 			if (disposed) return;
 			disposed = true;
+			animationControls?.dispose();
 			root.remove();
+		},
+		get animation() {
+			return animationControls;
 		}
 	};
 };

package/dist/es/renderToSvgString.d.ts

@@ -2,7 +2,8 @@ import { RenderInput, RenderToStringOptions } from './types';
 /**
  * 把 IR / Scene / Figure 渲染成 SVG 字符串（SSR / 构建期）
  * @description 收 `Figure` 时 delegate 给 `figure.toSvgString`。收 IR/Scene 时薄包 `@retikz/render/svg`：`toScene`
- *   （ir 缺省走 core fallback measurer、确定性）→ 序列化 → 若给 `width`/`height` 注入根 `<svg>`。零 DOM。
+ *   （ir 缺省走 core fallback measurer、确定性）→ 序列化。`width`/`height` 直接透传给 render，由其结构化写进根
+ *   `<svg>` attrs（不在本层对字符串做正则后处理）。零 DOM。
  */
 export declare const renderToSvgString: (input: RenderInput, options?: RenderToStringOptions) => string;
 //# sourceMappingURL=renderToSvgString.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"renderToSvgString.d.ts","sourceRoot":"","sources":["../../src/renderToSvgString.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAYlE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,WAAW,EAAE,UAAS,qBAA0B,KAAG,MAI3F,CAAC"}
+{"version":3,"file":"renderToSvgString.d.ts","sourceRoot":"","sources":["../../src/renderToSvgString.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,WAAW,EAAE,UAAS,qBAA0B,KAAG,MAU3F,CAAC"}

package/dist/es/renderToSvgString.js

@@ -2,22 +2,22 @@ import { isFigure } from "./builder/isFigure.js";
 import { toScene } from "./toScene.js";
 import { renderToSvgString } from "@retikz/render/svg";
 //#region src/renderToSvgString.ts
-/** 默认资源 id 前缀（确定性）；多实例同页须经 `options.idPrefix` 显式区分 */
-var DEFAULT_ID_PREFIX = "r";
-/** 把 `width`/`height` 注入到开头的 `<svg` 标签（@retikz/render/svg 只产 viewBox） */
-var injectSize = (svg, width, height) => {
-	if (width === void 0 && height === void 0) return svg;
-	const attrs = [width !== void 0 ? ` width="${width}"` : "", height !== void 0 ? ` height="${height}"` : ""].join("");
-	return svg.replace(/^<svg/, `<svg${attrs}`);
-};
 /**
 * 把 IR / Scene / Figure 渲染成 SVG 字符串（SSR / 构建期）
 * @description 收 `Figure` 时 delegate 给 `figure.toSvgString`。收 IR/Scene 时薄包 `@retikz/render/svg`：`toScene`
-*   （ir 缺省走 core fallback measurer、确定性）→ 序列化 → 若给 `width`/`height` 注入根 `<svg>`。零 DOM。
+*   （ir 缺省走 core fallback measurer、确定性）→ 序列化。`width`/`height` 直接透传给 render，由其结构化写进根
+*   `<svg>` attrs（不在本层对字符串做正则后处理）。零 DOM。
 */
 var renderToSvgString$1 = (input, options = {}) => {
 	if (isFigure(input)) return input.toSvgString(options);
-	return injectSize(renderToSvgString(toScene(input, options), { idPrefix: options.idPrefix ?? DEFAULT_ID_PREFIX }), options.width, options.height);
+	return renderToSvgString(toScene(input, options), {
+		idPrefix: options.idPrefix ?? "r",
+		animate: options.animate,
+		snapshotAt: options.snapshotAt,
+		easings: options.easings,
+		width: options.width,
+		height: options.height
+	});
 };
 //#endregion
 export { renderToSvgString$1 as renderToSvgString };

package/dist/es/types.d.ts

@@ -1,6 +1,8 @@
 import { CompileOptions, IR, Scene } from '@retikz/core';
 import { HydrationHandlers } from '@retikz/render/hydration';
+import { AnimationControls, AnimationPropertyRegistry, EasingRegistry } from '@retikz/render/animation';
 import { Figure } from './figure';
+export type { AnimationControls } from '@retikz/render/animation';
 /** mountSvg / renderToSvgString 的入参：已编译 `Scene`、待编译 `IR`，或命令式 builder 的 `Figure` */
 export type RenderInput = Scene | IR | Figure;
 /**
@@ -14,6 +16,18 @@ export type CommonOptions = {
     idPrefix?: string;
     width?: number;
     height?: number;
+    /**
+     * 是否播放动画（缺省 true）；`false` → 渲染 base 静态图（不 emit CSS/WAAPI、Canvas 不起 rAF）
+     * @description runtime 据 `{animate:false}` 或 `prefers-reduced-motion` 走静态路径（ADR-01「三事一路」）。
+     */
+    animate?: boolean;
+    /**
+     * 静态截帧时刻（毫秒）；给定时渲染「定格在该时刻」的静态图（不播放、不 emit 动画），SSR 海报帧 / 缩略图用
+     * @description SVG 后端把各 track 在该时刻的值烘焙成静态属性 / transform（复用 `evaluateTrack`）；覆盖 `animate`。
+     */
+    snapshotAt?: number;
+    /** 自定义 easing 注册表（透传 renderer / runtime） */
+    easings?: EasingRegistry;
 } & CompileOptions;
 export type RenderToStringOptions = CommonOptions;
 export type MountOptions = CommonOptions;
@@ -25,16 +39,33 @@ export type VanillaView = {
     update: (next: RenderInput) => void;
     /** 卸载：移除 `root`、置 view 失效（再调 `update` 抛、`dispose` noop） */
     dispose: () => void;
+    /**
+     * 绑定 handler 到本 view 的 `<svg>`（locateSvg 定位）；handler 收 `(event, context)` 富上下文
+     * @description context 由本 view 的 Scene 构造（meta / geometry / per-id 动画控制），读 live `currentScene`——
+     *   `update` 后 context 自动反映新图（无需重 hydrate）。`HydrateOptions.scene` / `renderer` 在 view.hydrate 下忽略。
+     */
+    hydrate: (options: HydrateOptions) => HydrationHandle;
+    /** 动画播放控制句柄（scene 含动画且未降级时存在）：play / pause / seek；manual trigger 经此驱动 */
+    animation?: AnimationControls;
 };
 /** `hydrate` / `view.hydrate` 返回的解绑句柄 */
 export type HydrationHandle = {
     /** 解绑本次水合的全部 listener，之后事件不再触发 */
     dispose: () => void;
 };
-/** 水合入参：按 id 提供的 handler 注册表（事件名 → handler） */
+/**
+ * 水合入参：按 id 提供的 handler 注册表（事件名 → handler）+ 可选 Scene（富 context 来源）
+ * @description `view.hydrate`（mountSvg / mountCanvas）忽略 `scene` / `renderer`、用自身 Scene 构造富 context；
+ *   standalone `hydrate(root, options)`（SSR 后独立入口）传 `scene` → 富 context（meta / geometry / 动画），
+ *   不传 → 最小 context（id + element + root + point，`meta` / `geometry` / `scene` undefined、`animation` no-op）。
+ */
 export type HydrateOptions = {
     /** id → 事件名 → handler 的注册表（透传给 `@retikz/render/hydration` 控制器） */
     handlers: HydrationHandlers;
+    /** 富 context 来源 Scene（仅 standalone `hydrate` 用；不传则最小 context）；可经 `toScene(ir)` 得到 */
+    scene?: Scene;
+    /** standalone `hydrate` 的渲染后端（缺省 `'svg'`）；决定 context.renderer 与 element 定位口径 */
+    renderer?: 'svg' | 'canvas';
 };
 /** Scene user units 坐标点（hitTest 入参 / 坐标映射出参） */
 export type ScenePoint = {
@@ -63,10 +94,14 @@ export type CanvasView = {
      *   交给 `hitTest` 自然判为无命中（无需在此截断），故无 `null` 返回。
      */
     clientToScene: (clientX: number, clientY: number) => ScenePoint;
+    /** 动画播放控制句柄（scene 含动画且未降级时存在）：rAF 时钟的 play / pause / seek */
+    animation?: AnimationControls;
 };
 /** `mountCanvas` 选项：继承 SSR / compile 公共项，外加 canvas 显示 / dpr 透传 */
 export type MountCanvasOptions = CommonOptions & {
     /** 设备像素比；缺省读 `globalThis.devicePixelRatio`、再回退 1（镜像 react CanvasHost） */
     devicePixelRatio?: number;
+    /** 自定义 property 插值器注册表（透传 drawScene；自定义动画通道用） */
+    animationProperties?: AnimationPropertyRegistry;
 };
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,oFAAoF;AACpF,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,EAAE,GAAG,MAAM,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,cAAc,CAAC;AAEnB,MAAM,MAAM,qBAAqB,GAAG,aAAa,CAAC;AAClD,MAAM,MAAM,YAAY,GAAG,aAAa,CAAC;AAEzC,6DAA6D;AAC7D,MAAM,MAAM,WAAW,GAAG;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,gEAAgE;IAChE,MAAM,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;IACpC,2DAA2D;IAC3D,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF,yCAAyC;AACzC,MAAM,MAAM,eAAe,GAAG;IAC5B,kCAAkC;IAClC,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF,+CAA+C;AAC/C,MAAM,MAAM,cAAc,GAAG;IAC3B,kEAAkE;IAClE,QAAQ,EAAE,iBAAiB,CAAC;CAC7B,CAAC;AAEF,gDAAgD;AAChD,MAAM,MAAM,UAAU,GAAG;IACvB,2BAA2B;IAC3B,CAAC,EAAE,MAAM,CAAC;IACV,2BAA2B;IAC3B,CAAC,EAAE,MAAM,CAAC;CACX,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,iDAAiD;IACjD,MAAM,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;IACpC,gEAAgE;IAChE,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,4FAA4F;IAC5F,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,eAAe,CAAC;IACtD;;;;OAIG;IACH,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,UAAU,CAAC;CACjE,CAAC;AAEF,kEAAkE;AAClE,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG;IAC/C,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC7G,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,oFAAoF;AACpF,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,EAAE,GAAG,MAAM,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B,GAAG,cAAc,CAAC;AAEnB,MAAM,MAAM,qBAAqB,GAAG,aAAa,CAAC;AAClD,MAAM,MAAM,YAAY,GAAG,aAAa,CAAC;AAEzC,6DAA6D;AAC7D,MAAM,MAAM,WAAW,GAAG;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,gEAAgE;IAChE,MAAM,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;IACpC,2DAA2D;IAC3D,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB;;;;OAIG;IACH,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,eAAe,CAAC;IACtD,yEAAyE;IACzE,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B,CAAC;AAEF,yCAAyC;AACzC,MAAM,MAAM,eAAe,GAAG;IAC5B,kCAAkC;IAClC,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,kEAAkE;IAClE,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,qFAAqF;IACrF,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,gFAAgF;IAChF,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;CAC7B,CAAC;AAEF,gDAAgD;AAChD,MAAM,MAAM,UAAU,GAAG;IACvB,2BAA2B;IAC3B,CAAC,EAAE,MAAM,CAAC;IACV,2BAA2B;IAC3B,CAAC,EAAE,MAAM,CAAC;CACX,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,iDAAiD;IACjD,MAAM,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;IACpC,gEAAgE;IAChE,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,4FAA4F;IAC5F,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,eAAe,CAAC;IACtD;;;;OAIG;IACH,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,UAAU,CAAC;IAChE,6DAA6D;IAC7D,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B,CAAC;AAEF,kEAAkE;AAClE,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG;IAC/C,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iDAAiD;IACjD,mBAAmB,CAAC,EAAE,yBAAyB,CAAC;CACjD,CAAC"}