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

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,7 +1,7 @@
 {
   "name": "@retikz/vanilla",
-  "version": "0.3.0-alpha.4",
-  "description": "Framework-free runtime for retikz: mount Scene/IR to SVG DOM, or render to SVG string for SSR.",
+  "version": "0.3.0-beta.1",
+  "description": "Framework-free retikz runtime: mount SVG/Canvas, hydrate interactions, control animations, or render SVG strings for SSR.",
   "type": "module",
   "author": "Pionpill",
   "homepage": "https://pionpill.github.io/retikz/",
@@ -39,15 +39,14 @@
     "dist/**/*"
   ],
   "dependencies": {
-    "@retikz/core": "0.3.0-alpha.4",
-    "@retikz/render": "0.3.0-alpha.4"
+    "@retikz/core": "0.3.0-beta.1",
+    "@retikz/render": "0.3.0-beta.1"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
     "typescript": "^6.0.3",
     "vite": "^8.0.10",
     "vite-plugin-dts": "^4.5.4",
-    "vite-tsconfig-paths": "^6.1.1",
     "vitest": "^4.1.5",
     "zod": "^3.23.8"
   },