@retikz/vanilla 0.3.0-alpha.3 → 0.3.0-alpha.5

package/README.md

@@ -1,50 +1,50 @@
-# @retikz/vanilla
-
-Framework-free runtime + SSR entry for [retikz](https://pionpill.github.io/retikz/). No JSX, no UI framework — mount a diagram to the DOM, render it to an SVG string on the server, or compose one with an imperative named builder.
-
-retikz 的无框架 runtime / SSR 入口：不依赖任何 UI 框架。`renderToSvgString` 走服务端 / 构建期（零 DOM）产 SVG 字符串；`mountSvg` 在浏览器把图形挂到 DOM；命令式 builder（`figure`/`node`/`draw`/`coordinate`/`scope`）让你像 React 一样具名构图、产同一份 IR。组合 `@retikz/render` 内核，不自维护第二套渲染逻辑。
-
-## Install
-
-```bash
-pnpm add @retikz/vanilla @retikz/core @retikz/render
-```
-
-## Render IR / Scene
-
-```ts
-import { renderToSvgString, mountSvg } from '@retikz/vanilla';
-
-// server / build time — no DOM
-const svg = renderToSvgString(ir);
-
-// browser
-mountSvg(document.querySelector('#diagram'), ir);
-```
-
-## Imperative builder
-
-```ts
-import { figure, node, draw } from '@retikz/vanilla';
-
-const fig = figure([
-  node('a', { position: [0, 0], text: 'A' }),
-  node('b', { position: [120, 0], text: 'B' }),
-  draw(['a', 'b'], { arrow: '->' }),
-]);
-
-const svg = fig.toSvgString();   // also: fig.mount(el) / fig.toCanvas(canvas)
-```
-
-## Exports
-
-- Runtime: `renderToSvgString`, `mountSvg`
-- Builder: `figure` / `node` / `draw` / `coordinate` / `scope` + the `Figure` view (`.toSvgString` / `.mount` / `.toCanvas`)
-
-## Docs
-
-<https://pionpill.github.io/retikz/>
-
-## License
-
-MIT
+# @retikz/vanilla
+
+Framework-free runtime + SSR entry for [retikz](https://pionpill.github.io/retikz/). No JSX, no UI framework — mount a diagram to the DOM, render it to an SVG string on the server, or compose one with an imperative named builder.
+
+retikz 的无框架 runtime / SSR 入口：不依赖任何 UI 框架。`renderToSvgString` 走服务端 / 构建期（零 DOM）产 SVG 字符串；`mountSvg` 在浏览器把图形挂到 DOM；命令式 builder（`figure`/`node`/`draw`/`coordinate`/`scope`）让你像 React 一样具名构图、产同一份 IR。组合 `@retikz/render` 内核，不自维护第二套渲染逻辑。
+
+## Install
+
+```bash
+pnpm add @retikz/vanilla @retikz/core @retikz/render
+```
+
+## Render IR / Scene
+
+```ts
+import { renderToSvgString, mountSvg } from '@retikz/vanilla';
+
+// server / build time — no DOM
+const svg = renderToSvgString(ir);
+
+// browser
+mountSvg(document.querySelector('#diagram'), ir);
+```
+
+## Imperative builder
+
+```ts
+import { figure, node, draw } from '@retikz/vanilla';
+
+const fig = figure([
+  node('a', { position: [0, 0], text: 'A' }),
+  node('b', { position: [120, 0], text: 'B' }),
+  draw(['a', 'b'], { arrow: '->' }),
+]);
+
+const svg = fig.toSvgString();   // also: fig.mount(el) / fig.toCanvas(canvas)
+```
+
+## Exports
+
+- Runtime: `renderToSvgString`, `mountSvg`
+- Builder: `figure` / `node` / `draw` / `coordinate` / `scope` + the `Figure` view (`.toSvgString` / `.mount` / `.toCanvas`)
+
+## Docs
+
+<https://pionpill.github.io/retikz/>
+
+## License
+
+MIT

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,9 @@ export { renderToSvgString } from './renderToSvgString';
 export { mountSvg } from './mountSvg';
 export { hydrate } from './hydrate';
 export { mountCanvas } from './mountCanvas';
+export type { RetikzEventName, 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 { figure } from './builder/figure';
 export { node } from './builder/node';
 export { draw } from './builder/draw';
@@ -18,5 +21,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,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"}

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 { 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 };

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":"AAYA,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,UA6JF,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 { createCanvasIdAnimationControls, createHydrationController, geometryOf, metaOf } from "@retikz/render/hydration";
 import { hitTest, renderToCanvas } from "@retikz/render/canvas";
 //#region src/mountCanvas.ts
 /** 设备像素比：取有限正数、否则回退 1（镜像 react CanvasHost） */
@@ -20,7 +21,27 @@ var mountCanvas = (container, input, 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 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 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,6 +55,21 @@ 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();
+		}
 	};
 	renderInto(isFigure(input) ? input.ir : input);
 	container.appendChild(canvas);
@@ -68,11 +104,32 @@ 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 = (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
+			};
+		};
+		return { dispose: createHydrationController(canvas, hydrateOptions.handlers, locate, buildContext).dispose };
 	};
 	return {
 		root: canvas,
@@ -83,10 +140,14 @@ var mountCanvas = (container, input, options = {}) => {
 		dispose() {
 			if (disposed) return;
 			disposed = true;
+			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":"AAgBA,OAAO,KAAK,EAAmC,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAMvG;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GAAI,WAAW,OAAO,EAAE,OAAO,WAAW,EAAE,UAAS,YAAiB,KAAG,WA4E7F,CAAC"}

package/dist/es/mountSvg.js

@@ -2,6 +2,8 @@ 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 { createHydrationController, createSvgAnimationControls, geometryOf, locateSvg, metaOf, resolvePointViaLayout, resolveSvgElement } from "@retikz/render/hydration";
 //#region src/mountSvg.ts
 var SVG_NS = "http://www.w3.org/2000/svg";
 /** 默认资源 id 前缀（确定性）；多实例同页须经 `options.idPrefix` 显式区分 */
@@ -18,18 +20,50 @@ var mountSvg = (container, input, 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 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 = (event, id) => ({
+			id,
+			meta: metaOf(currentScene, id),
+			renderer: "svg",
+			element: resolveSvgElement(event),
+			root,
+			point: resolvePointViaLayout(root, currentScene.layout)(event),
+			geometry: geometryOf(currentScene, id),
+			animation: createSvgAnimationControls(root, id),
+			scene: currentScene
+		});
+		return { dispose: createHydrationController(root, hydrateOptions.handlers, locateSvg, buildContext).dispose };
+	};
 	let disposed = false;
 	return {
 		root,
@@ -37,10 +71,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.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":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAYlE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,WAAW,EAAE,UAAS,qBAA0B,KAAG,MAS3F,CAAC"}

package/dist/es/renderToSvgString.js

@@ -17,7 +17,12 @@ var injectSize = (svg, width, height) => {
 */
 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 injectSize(renderToSvgString(toScene(input, options), {
+		idPrefix: options.idPrefix ?? DEFAULT_ID_PREFIX,
+		animate: options.animate,
+		snapshotAt: options.snapshotAt,
+		easings: options.easings
+	}), options.width, 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"}

package/dist/lib/hydrate.cjs

@@ -1,14 +1,30 @@
 let _retikz_render_hydration = require("@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: (0, _retikz_render_hydration.createHydrationController)(root, options.handlers, _retikz_render_hydration.locateSvg).dispose };
+	const renderer = options.renderer ?? "svg";
+	const scene = options.scene;
+	const buildContext = (0, _retikz_render_hydration.createContextBuilder)({
+		renderer,
+		root,
+		scene,
+		resolveElement: _retikz_render_hydration.resolveSvgElement,
+		resolvePoint: scene ? (0, _retikz_render_hydration.resolvePointViaLayout)(root, scene.layout) : (0, _retikz_render_hydration.resolveSvgPointViaCtm)(root),
+		makeAnimation: scene ? (id) => (0, _retikz_render_hydration.createSvgAnimationControls)(root, id) : () => _retikz_render_hydration.noopAnimationControls
+	});
+	return { dispose: (0, _retikz_render_hydration.createHydrationController)(root, options.handlers, _retikz_render_hydration.locateSvg, buildContext).dispose };
 };
 //#endregion
 exports.hydrate = hydrate;

package/dist/lib/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/lib/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/lib/index.cjs

@@ -8,12 +8,103 @@ const require_draw = require("./builder/draw.cjs");
 const require_node = require("./builder/node.cjs");
 const require_scope = require("./builder/scope.cjs");
 const require_figure = require("./builder/figure.cjs");
+let _retikz_core = require("@retikz/core");
+Object.defineProperty(exports, "blink", {
+	enumerable: true,
+	get: function() {
+		return _retikz_core.blink;
+	}
+});
+Object.defineProperty(exports, "cameraTo", {
+	enumerable: true,
+	get: function() {
+		return _retikz_core.cameraTo;
+	}
+});
+Object.defineProperty(exports, "colorShift", {
+	enumerable: true,
+	get: function() {
+		return _retikz_core.colorShift;
+	}
+});
 exports.coordinate = require_coordinate.coordinate;
 exports.draw = require_draw.draw;
+Object.defineProperty(exports, "drawOn", {
+	enumerable: true,
+	get: function() {
+		return _retikz_core.drawOn;
+	}
+});
+Object.defineProperty(exports, "fadeIn", {
+	enumerable: true,
+	get: function() {
+		return _retikz_core.fadeIn;
+	}
+});
 exports.figure = require_figure.figure;
+Object.defineProperty(exports, "flash", {
+	enumerable: true,
+	get: function() {
+		return _retikz_core.flash;
+	}
+});
+Object.defineProperty(exports, "grow", {
+	enumerable: true,
+	get: function() {
+		return _retikz_core.grow;
+	}
+});
+Object.defineProperty(exports, "growUp", {
+	enumerable: true,
+	get: function() {
+		return _retikz_core.growUp;
+	}
+});
 exports.hydrate = require_hydrate.hydrate;
+Object.defineProperty(exports, "loop", {
+	enumerable: true,
+	get: function() {
+		return _retikz_core.loop;
+	}
+});
 exports.mountCanvas = require_mountCanvas.mountCanvas;
 exports.mountSvg = require_mountSvg.mountSvg;
 exports.node = require_node.node;
+Object.defineProperty(exports, "pulse", {
+	enumerable: true,
+	get: function() {
+		return _retikz_core.pulse;
+	}
+});
 exports.renderToSvgString = require_renderToSvgString.renderToSvgString;
+Object.defineProperty(exports, "scaleIn", {
+	enumerable: true,
+	get: function() {
+		return _retikz_core.scaleIn;
+	}
+});
 exports.scope = require_scope.scope;
+Object.defineProperty(exports, "slideIn", {
+	enumerable: true,
+	get: function() {
+		return _retikz_core.slideIn;
+	}
+});
+Object.defineProperty(exports, "spin", {
+	enumerable: true,
+	get: function() {
+		return _retikz_core.spin;
+	}
+});
+Object.defineProperty(exports, "stagger", {
+	enumerable: true,
+	get: function() {
+		return _retikz_core.stagger;
+	}
+});
+Object.defineProperty(exports, "wiggle", {
+	enumerable: true,
+	get: function() {
+		return _retikz_core.wiggle;
+	}
+});

package/dist/lib/index.d.ts

@@ -10,6 +10,9 @@ export { renderToSvgString } from './renderToSvgString';
 export { mountSvg } from './mountSvg';
 export { hydrate } from './hydrate';
 export { mountCanvas } from './mountCanvas';
+export type { RetikzEventName, 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 { figure } from './builder/figure';
 export { node } from './builder/node';
 export { draw } from './builder/draw';
@@ -18,5 +21,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/lib/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,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"}

package/dist/lib/mountCanvas.cjs

@@ -1,5 +1,6 @@
 const require_isFigure = require("./builder/isFigure.cjs");
 const require_toScene = require("./toScene.cjs");
+let _retikz_render_animation = require("@retikz/render/animation");
 let _retikz_render_hydration = require("@retikz/render/hydration");
 let _retikz_render_canvas = require("@retikz/render/canvas");
 //#region src/mountCanvas.ts
@@ -20,7 +21,27 @@ var mountCanvas = (container, input, 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 && !(0, _retikz_render_animation.prefersReducedMotion)();
+	let clock;
+	const registry = (0, _retikz_render_animation.createIdClockRegistry)();
 	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;
+		(0, _retikz_render_canvas.renderToCanvas)(canvas, currentScene, {
+			devicePixelRatio: ratio,
+			time,
+			easings: options.easings,
+			animationProperties: options.animationProperties,
+			resolvePrimAnimation: (id) => resolvePrim(id, time)
+		});
+	};
 	const renderInto = (next) => {
 		if (require_isFigure.isFigure(next)) throw new Error("mountCanvas: view.update does not accept a Figure; pass figure.ir instead.");
 		const scene = require_toScene.toScene(next, options);
@@ -34,6 +55,21 @@ var mountCanvas = (container, input, options = {}) => {
 		if (options.height !== void 0) canvas.style.height = `${options.height}px`;
 		canvas.style.objectFit = "contain";
 		(0, _retikz_render_canvas.renderToCanvas)(canvas, scene, { devicePixelRatio: ratio });
+		clock?.dispose();
+		clock = void 0;
+		if (animate && (0, _retikz_render_animation.sceneHasAnimations)(scene)) {
+			clock = (0, _retikz_render_animation.createClock)({
+				durationMs: (0, _retikz_render_animation.sceneAnimationDurationMs)(scene),
+				onFrame: (time) => (0, _retikz_render_canvas.renderToCanvas)(canvas, currentScene, {
+					devicePixelRatio: ratio,
+					time,
+					easings: options.easings,
+					animationProperties: options.animationProperties,
+					resolvePrimAnimation: (id) => resolvePrim(id, time)
+				})
+			});
+			if ((0, _retikz_render_animation.sceneHasAutoplayTrigger)(scene)) clock.play();
+		}
 	};
 	renderInto(require_isFigure.isFigure(input) ? input.ir : input);
 	container.appendChild(canvas);
@@ -68,11 +104,32 @@ var mountCanvas = (container, input, options = {}) => {
 	*/
 	const hydrate = (hydrateOptions) => {
 		const context2d = canvas.getContext("2d") ?? void 0;
-		return { dispose: (0, _retikz_render_hydration.createHydrationController)(canvas, hydrateOptions.handlers, (event) => {
+		const locate = (event) => {
 			const scenePoint = clientToScene(event.clientX, event.clientY);
 			context2d?.setTransform(1, 0, 0, 1, 0, 0);
 			return (0, _retikz_render_canvas.hitTest)(currentScene, scenePoint, { context2d });
-		}).dispose };
+		};
+		const buildContext = (event, id) => {
+			const mouse = event;
+			return {
+				id,
+				meta: (0, _retikz_render_hydration.metaOf)(currentScene, id),
+				renderer: "canvas",
+				element: null,
+				root: canvas,
+				point: typeof mouse.clientX === "number" ? clientToScene(mouse.clientX, mouse.clientY) : null,
+				geometry: (0, _retikz_render_hydration.geometryOf)(currentScene, id),
+				animation: (0, _retikz_render_hydration.createCanvasIdAnimationControls)({
+					registry,
+					clockTime: () => clock?.time ?? 0,
+					ensurePlaying: () => clock?.play(),
+					renderFrame,
+					defaultId: id
+				}),
+				scene: currentScene
+			};
+		};
+		return { dispose: (0, _retikz_render_hydration.createHydrationController)(canvas, hydrateOptions.handlers, locate, buildContext).dispose };
 	};
 	return {
 		root: canvas,
@@ -83,10 +140,14 @@ var mountCanvas = (container, input, options = {}) => {
 		dispose() {
 			if (disposed) return;
 			disposed = true;
+			clock?.dispose();
 			canvas.remove();
 		},
 		hydrate,
-		clientToScene
+		clientToScene,
+		get animation() {
+			return clock;
+		}
 	};
 };
 //#endregion

package/dist/lib/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":"AAYA,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,UA6JF,CAAC"}

package/dist/lib/mountSvg.cjs

@@ -2,6 +2,8 @@ const require_isFigure = require("./builder/isFigure.cjs");
 const require_toScene = require("./toScene.cjs");
 const require_svgNodeToDom = require("./svgNodeToDom.cjs");
 let _retikz_render_svg = require("@retikz/render/svg");
+let _retikz_render_animation = require("@retikz/render/animation");
+let _retikz_render_hydration = require("@retikz/render/hydration");
 //#region src/mountSvg.ts
 var SVG_NS = "http://www.w3.org/2000/svg";
 /** 默认资源 id 前缀（确定性）；多实例同页须经 `options.idPrefix` 显式区分 */
@@ -18,18 +20,50 @@ var mountSvg = (container, input, 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 root = document.createElementNS(SVG_NS, "svg");
+	const animate = options.animate !== false && !(0, _retikz_render_animation.prefersReducedMotion)();
+	let animationControls;
+	let currentScene;
 	const renderInto = (next) => {
 		if (require_isFigure.isFigure(next)) throw new Error("mountSvg: view.update does not accept a Figure; pass figure.ir instead.");
-		const doc = (0, _retikz_render_svg.buildSvgDocument)(require_toScene.toScene(next, options), { idPrefix });
+		const scene = require_toScene.toScene(next, options);
+		currentScene = scene;
+		const doc = (0, _retikz_render_svg.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);
 		require_svgNodeToDom.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) : require_svgNodeToDom.svgNodeToDom(child));
+		animationControls?.dispose();
+		animationControls = animate && (0, _retikz_render_animation.sceneHasAnimations)(scene) ? (0, _retikz_render_animation.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 = (event, id) => ({
+			id,
+			meta: (0, _retikz_render_hydration.metaOf)(currentScene, id),
+			renderer: "svg",
+			element: (0, _retikz_render_hydration.resolveSvgElement)(event),
+			root,
+			point: (0, _retikz_render_hydration.resolvePointViaLayout)(root, currentScene.layout)(event),
+			geometry: (0, _retikz_render_hydration.geometryOf)(currentScene, id),
+			animation: (0, _retikz_render_hydration.createSvgAnimationControls)(root, id),
+			scene: currentScene
+		});
+		return { dispose: (0, _retikz_render_hydration.createHydrationController)(root, hydrateOptions.handlers, _retikz_render_hydration.locateSvg, buildContext).dispose };
+	};
 	let disposed = false;
 	return {
 		root,
@@ -37,10 +71,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/lib/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":"AAgBA,OAAO,KAAK,EAAmC,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAMvG;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GAAI,WAAW,OAAO,EAAE,OAAO,WAAW,EAAE,UAAS,YAAiB,KAAG,WA4E7F,CAAC"}

package/dist/lib/renderToSvgString.cjs

@@ -17,7 +17,12 @@ var injectSize = (svg, width, height) => {
 */
 var renderToSvgString = (input, options = {}) => {
 	if (require_isFigure.isFigure(input)) return input.toSvgString(options);
-	return injectSize((0, _retikz_render_svg.renderToSvgString)(require_toScene.toScene(input, options), { idPrefix: options.idPrefix ?? DEFAULT_ID_PREFIX }), options.width, options.height);
+	return injectSize((0, _retikz_render_svg.renderToSvgString)(require_toScene.toScene(input, options), {
+		idPrefix: options.idPrefix ?? DEFAULT_ID_PREFIX,
+		animate: options.animate,
+		snapshotAt: options.snapshotAt,
+		easings: options.easings
+	}), options.width, options.height);
 };
 //#endregion
 exports.renderToSvgString = renderToSvgString;

package/dist/lib/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":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAYlE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,WAAW,EAAE,UAAS,qBAA0B,KAAG,MAS3F,CAAC"}

package/dist/lib/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/lib/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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retikz/vanilla",
-  "version": "0.3.0-alpha.3",
+  "version": "0.3.0-alpha.5",
   "description": "Framework-free runtime for retikz: mount Scene/IR to SVG DOM, or render to SVG string for SSR.",
   "type": "module",
   "author": "Pionpill",
@@ -16,7 +16,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Pionpill/retikz.git",
-    "directory": "packages/vanilla"
+    "directory": "packages/core/vanilla"
   },
   "bugs": {
     "url": "https://github.com/Pionpill/retikz/issues"
@@ -39,8 +39,8 @@
     "dist/**/*"
   ],
   "dependencies": {
-    "@retikz/core": "0.3.0-alpha.3",
-    "@retikz/render": "0.3.0-alpha.3"
+    "@retikz/core": "0.3.0-alpha.5",
+    "@retikz/render": "0.3.0-alpha.5"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",