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

package/dist/es/hydrate.d.ts

@@ -0,0 +1,10 @@
+import { HydrateOptions, HydrationHandle } from './types';
+/**
+ * 把用户 handler 水合到容器内已挂的 `<svg>`（无框架 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 }` 解绑。
+ */
+export declare const hydrate: (root: Element, options: HydrateOptions) => HydrationHandle;
+//# sourceMappingURL=hydrate.d.ts.map

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

@@ -0,0 +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"}

package/dist/es/hydrate.js

@@ -0,0 +1,14 @@
+import { createHydrationController, locateSvg } from "@retikz/render/hydration";
+//#region src/hydrate.ts
+/**
+* 把用户 handler 水合到容器内已挂的 `<svg>`（无框架 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 }` 解绑。
+*/
+var hydrate = (root, options) => {
+	return { dispose: createHydrationController(root, options.handlers, locateSvg).dispose };
+};
+//#endregion
+export { hydrate };

package/dist/es/index.d.ts

@@ -8,6 +8,8 @@
  */
 export { renderToSvgString } from './renderToSvgString';
 export { mountSvg } from './mountSvg';
+export { hydrate } from './hydrate';
+export { mountCanvas } from './mountCanvas';
 export { figure } from './builder/figure';
 export { node } from './builder/node';
 export { draw } from './builder/draw';
@@ -16,5 +18,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 } from './types';
+export type { RenderInput, CommonOptions, MountOptions, RenderToStringOptions, VanillaView, CanvasView, MountCanvasOptions, HydrateOptions, HydrationHandle, ScenePoint, } 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,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,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,qBAAqB,EAAE,WAAW,EAAE,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;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"}

package/dist/es/index.js

@@ -1,8 +1,10 @@
 import { renderToSvgString } from "./renderToSvgString.js";
 import { mountSvg } from "./mountSvg.js";
+import { hydrate } from "./hydrate.js";
+import { mountCanvas } from "./mountCanvas.js";
 import { coordinate } from "./builder/coordinate.js";
 import { draw } from "./builder/draw.js";
 import { node } from "./builder/node.js";
 import { scope } from "./builder/scope.js";
 import { figure } from "./builder/figure.js";
-export { coordinate, draw, figure, mountSvg, node, renderToSvgString, scope };
+export { coordinate, draw, figure, hydrate, mountCanvas, mountSvg, node, renderToSvgString, scope };

package/dist/es/mountCanvas.d.ts

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

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

@@ -0,0 +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"}

package/dist/es/mountCanvas.js

@@ -0,0 +1,93 @@
+import { isFigure } from "./builder/isFigure.js";
+import { toScene } from "./toScene.js";
+import { createHydrationController } from "@retikz/render/hydration";
+import { hitTest, renderToCanvas } from "@retikz/render/canvas";
+//#region src/mountCanvas.ts
+/** 设备像素比：取有限正数、否则回退 1（镜像 react CanvasHost） */
+var resolveDevicePixelRatio = (override) => {
+	if (typeof override === "number" && Number.isFinite(override) && override > 0) return override;
+	const ratio = globalThis.devicePixelRatio;
+	return typeof ratio === "number" && Number.isFinite(ratio) && ratio > 0 ? ratio : 1;
+};
+/**
+* 把 IR / Scene / Figure 挂成真实 `<canvas>` DOM（无框架浏览器 runtime，对齐 `mountSvg`）
+* @description 收 IR 时 `toScene` compile、收 Scene 直用、收 Figure 解 `figure.ir`。位图按「名义显示尺寸」
+*   `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 (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);
+	let currentScene;
+	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);
+		currentScene = scene;
+		const hasNominalSize = typeof options.width === "number" && Number.isFinite(options.width) && typeof options.height === "number" && Number.isFinite(options.height);
+		const bitmapWidth = hasNominalSize ? options.width : scene.layout.width;
+		const bitmapHeight = hasNominalSize ? options.height : scene.layout.height;
+		canvas.width = Math.max(1, Math.round(bitmapWidth * ratio));
+		canvas.height = Math.max(1, Math.round(bitmapHeight * ratio));
+		if (options.width !== void 0) canvas.style.width = `${options.width}px`;
+		if (options.height !== void 0) canvas.style.height = `${options.height}px`;
+		canvas.style.objectFit = "contain";
+		renderToCanvas(canvas, scene, { devicePixelRatio: ratio });
+	};
+	renderInto(isFigure(input) ? input.ir : input);
+	container.appendChild(canvas);
+	/**
+	* 把指针的 client 像素坐标逆 meet-fit 映射成 Scene user units
+	* @description meet-fit 正向（CSS 显示盒内，镜像 renderToCanvas / CanvasHost，dpr 在 client→CSS 这步已无关）：
+	*   `scale = min(cssWidth/layout.width, cssHeight/layout.height)`；`offset = (cssSize − layout.size·scale)/2`
+	*   居中 letterbox；`cssX = offset.x + (sceneX − layout.x)·scale`。此处求逆——读 `canvas.getBoundingClientRect()`
+	*   把 client 坐标降到 canvas 局部 CSS 像素，再去 letterbox offset、除 scale、加 layout origin。落在 letterbox
+	*   黑边外的点会得到 layout 区域外坐标，交由 `hitTest` 自然判为无命中（不在此截断）。
+	*/
+	const clientToScene = (clientX, clientY) => {
+		const { layout } = currentScene;
+		const rect = canvas.getBoundingClientRect();
+		const scale = Math.min(rect.width / layout.width, rect.height / layout.height);
+		const offsetX = (rect.width - layout.width * scale) / 2;
+		const offsetY = (rect.height - layout.height * scale) / 2;
+		const contentX = clientX - rect.left - offsetX;
+		const contentY = clientY - rect.top - offsetY;
+		return {
+			x: contentX / scale + layout.x,
+			y: contentY / scale + layout.y
+		};
+	};
+	let disposed = false;
+	/**
+	* canvas 水合：把 handler 经 hitTest 定位绑到 `<canvas>`
+	* @description canvas 无逐图元 DOM，`locate(event)` = client 坐标经 `clientToScene` 逆 meet-fit 成 Scene 点
+	*   （落 letterbox 黑边 → null、不命中），再 `hitTest(currentScene, point, { context2d })` 返回命中图元 id。
+	*   `context2d` 用 canvas 自己的 2D context（生产真实；测试 spy 的 harness context 经 `getContext('2d')` 返回）
+	*   作几何重建 + 原生点测的载体。绑定经 `createHydrationController`（根级委托 + enter/leave 合成 + dispose）。
+	*/
+	const hydrate = (hydrateOptions) => {
+		const context2d = canvas.getContext("2d") ?? void 0;
+		return { dispose: createHydrationController(canvas, hydrateOptions.handlers, (event) => {
+			const scenePoint = clientToScene(event.clientX, event.clientY);
+			context2d?.setTransform(1, 0, 0, 1, 0, 0);
+			return hitTest(currentScene, scenePoint, { context2d });
+		}).dispose };
+	};
+	return {
+		root: canvas,
+		update(next) {
+			if (disposed) throw new Error("mountCanvas: view already disposed.");
+			renderInto(next);
+		},
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			canvas.remove();
+		},
+		hydrate,
+		clientToScene
+	};
+};
+//#endregion
+export { mountCanvas };

package/dist/es/types.d.ts

@@ -1,4 +1,5 @@
 import { CompileOptions, IR, Scene } from '@retikz/core';
+import { HydrationHandlers } from '@retikz/render/hydration';
 import { Figure } from './figure';
 /** mountSvg / renderToSvgString 的入参：已编译 `Scene`、待编译 `IR`，或命令式 builder 的 `Figure` */
 export type RenderInput = Scene | IR | Figure;
@@ -25,4 +26,47 @@ export type VanillaView = {
     /** 卸载：移除 `root`、置 view 失效（再调 `update` 抛、`dispose` noop） */
     dispose: () => void;
 };
+/** `hydrate` / `view.hydrate` 返回的解绑句柄 */
+export type HydrationHandle = {
+    /** 解绑本次水合的全部 listener，之后事件不再触发 */
+    dispose: () => void;
+};
+/** 水合入参：按 id 提供的 handler 注册表（事件名 → handler） */
+export type HydrateOptions = {
+    /** id → 事件名 → handler 的注册表（透传给 `@retikz/render/hydration` 控制器） */
+    handlers: HydrationHandlers;
+};
+/** Scene user units 坐标点（hitTest 入参 / 坐标映射出参） */
+export type ScenePoint = {
+    /** Scene user units 横坐标 */
+    x: number;
+    /** Scene user units 纵坐标 */
+    y: number;
+};
+/**
+ * `mountCanvas` 返回的句柄：在 `VanillaView` 基础上加 canvas 侧水合 + 坐标映射
+ * @description `root` 是挂出的 `<canvas>`（非 svg），与 `mountSvg` 的 `<svg>` 对应；`hydrate` 用 `hitTest` +
+ *   client→Scene 坐标映射做定位；`clientToScene` 把指针的 client 像素逆 meet-fit 映射回 Scene user units（供 hitTest）。
+ */
+export type CanvasView = {
+    /** 挂载出的 `<canvas>`；跨 `update` 同一元素（不被替换） */
+    readonly root: HTMLCanvasElement;
+    /** 整图重渲染（原地复用 `root`、重设位图尺寸 + 重绘），不承诺局部 patch */
+    update: (next: RenderInput) => void;
+    /** 卸载：移除 `root`、解绑水合、置 view 失效（再调 `update` 抛、`dispose` noop） */
+    dispose: () => void;
+    /** 绑定 handler：以 `hitTest` + `clientToScene` 构造 `locate`，经 `createHydrationController` 委托 */
+    hydrate: (options: HydrateOptions) => HydrationHandle;
+    /**
+     * 把指针的 client 像素坐标逆 meet-fit 映射成 Scene user units（命中映射用）
+     * @description 始终返回逆 fit 后的 Scene 点；落在 letterbox 黑边外的点会得到 layout 区域外坐标，
+     *   交给 `hitTest` 自然判为无命中（无需在此截断），故无 `null` 返回。
+     */
+    clientToScene: (clientX: number, clientY: number) => ScenePoint;
+};
+/** `mountCanvas` 选项：继承 SSR / compile 公共项，外加 canvas 显示 / dpr 透传 */
+export type MountCanvasOptions = CommonOptions & {
+    /** 设备像素比；缺省读 `globalThis.devicePixelRatio`、再回退 1（镜像 react CanvasHost） */
+    devicePixelRatio?: number;
+};
 //# 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,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"}
+{"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"}

package/dist/lib/hydrate.cjs

@@ -0,0 +1,14 @@
+let _retikz_render_hydration = require("@retikz/render/hydration");
+//#region src/hydrate.ts
+/**
+* 把用户 handler 水合到容器内已挂的 `<svg>`（无框架 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 }` 解绑。
+*/
+var hydrate = (root, options) => {
+	return { dispose: (0, _retikz_render_hydration.createHydrationController)(root, options.handlers, _retikz_render_hydration.locateSvg).dispose };
+};
+//#endregion
+exports.hydrate = hydrate;

package/dist/lib/hydrate.d.ts

@@ -0,0 +1,10 @@
+import { HydrateOptions, HydrationHandle } from './types';
+/**
+ * 把用户 handler 水合到容器内已挂的 `<svg>`（无框架 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 }` 解绑。
+ */
+export declare const hydrate: (root: Element, options: HydrateOptions) => HydrationHandle;
+//# sourceMappingURL=hydrate.d.ts.map

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

@@ -0,0 +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"}

package/dist/lib/index.cjs

@@ -1,6 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_renderToSvgString = require("./renderToSvgString.cjs");
 const require_mountSvg = require("./mountSvg.cjs");
+const require_hydrate = require("./hydrate.cjs");
+const require_mountCanvas = require("./mountCanvas.cjs");
 const require_coordinate = require("./builder/coordinate.cjs");
 const require_draw = require("./builder/draw.cjs");
 const require_node = require("./builder/node.cjs");
@@ -9,6 +11,8 @@ const require_figure = require("./builder/figure.cjs");
 exports.coordinate = require_coordinate.coordinate;
 exports.draw = require_draw.draw;
 exports.figure = require_figure.figure;
+exports.hydrate = require_hydrate.hydrate;
+exports.mountCanvas = require_mountCanvas.mountCanvas;
 exports.mountSvg = require_mountSvg.mountSvg;
 exports.node = require_node.node;
 exports.renderToSvgString = require_renderToSvgString.renderToSvgString;

package/dist/lib/index.d.ts

@@ -8,6 +8,8 @@
  */
 export { renderToSvgString } from './renderToSvgString';
 export { mountSvg } from './mountSvg';
+export { hydrate } from './hydrate';
+export { mountCanvas } from './mountCanvas';
 export { figure } from './builder/figure';
 export { node } from './builder/node';
 export { draw } from './builder/draw';
@@ -16,5 +18,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 } from './types';
+export type { RenderInput, CommonOptions, MountOptions, RenderToStringOptions, VanillaView, CanvasView, MountCanvasOptions, HydrateOptions, HydrationHandle, ScenePoint, } 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,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,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,qBAAqB,EAAE,WAAW,EAAE,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;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"}

package/dist/lib/mountCanvas.cjs

@@ -0,0 +1,93 @@
+const require_isFigure = require("./builder/isFigure.cjs");
+const require_toScene = require("./toScene.cjs");
+let _retikz_render_hydration = require("@retikz/render/hydration");
+let _retikz_render_canvas = require("@retikz/render/canvas");
+//#region src/mountCanvas.ts
+/** 设备像素比：取有限正数、否则回退 1（镜像 react CanvasHost） */
+var resolveDevicePixelRatio = (override) => {
+	if (typeof override === "number" && Number.isFinite(override) && override > 0) return override;
+	const ratio = globalThis.devicePixelRatio;
+	return typeof ratio === "number" && Number.isFinite(ratio) && ratio > 0 ? ratio : 1;
+};
+/**
+* 把 IR / Scene / Figure 挂成真实 `<canvas>` DOM（无框架浏览器 runtime，对齐 `mountSvg`）
+* @description 收 IR 时 `toScene` compile、收 Scene 直用、收 Figure 解 `figure.ir`。位图按「名义显示尺寸」
+*   `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 (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);
+	let currentScene;
+	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);
+		currentScene = scene;
+		const hasNominalSize = typeof options.width === "number" && Number.isFinite(options.width) && typeof options.height === "number" && Number.isFinite(options.height);
+		const bitmapWidth = hasNominalSize ? options.width : scene.layout.width;
+		const bitmapHeight = hasNominalSize ? options.height : scene.layout.height;
+		canvas.width = Math.max(1, Math.round(bitmapWidth * ratio));
+		canvas.height = Math.max(1, Math.round(bitmapHeight * ratio));
+		if (options.width !== void 0) canvas.style.width = `${options.width}px`;
+		if (options.height !== void 0) canvas.style.height = `${options.height}px`;
+		canvas.style.objectFit = "contain";
+		(0, _retikz_render_canvas.renderToCanvas)(canvas, scene, { devicePixelRatio: ratio });
+	};
+	renderInto(require_isFigure.isFigure(input) ? input.ir : input);
+	container.appendChild(canvas);
+	/**
+	* 把指针的 client 像素坐标逆 meet-fit 映射成 Scene user units
+	* @description meet-fit 正向（CSS 显示盒内，镜像 renderToCanvas / CanvasHost，dpr 在 client→CSS 这步已无关）：
+	*   `scale = min(cssWidth/layout.width, cssHeight/layout.height)`；`offset = (cssSize − layout.size·scale)/2`
+	*   居中 letterbox；`cssX = offset.x + (sceneX − layout.x)·scale`。此处求逆——读 `canvas.getBoundingClientRect()`
+	*   把 client 坐标降到 canvas 局部 CSS 像素，再去 letterbox offset、除 scale、加 layout origin。落在 letterbox
+	*   黑边外的点会得到 layout 区域外坐标，交由 `hitTest` 自然判为无命中（不在此截断）。
+	*/
+	const clientToScene = (clientX, clientY) => {
+		const { layout } = currentScene;
+		const rect = canvas.getBoundingClientRect();
+		const scale = Math.min(rect.width / layout.width, rect.height / layout.height);
+		const offsetX = (rect.width - layout.width * scale) / 2;
+		const offsetY = (rect.height - layout.height * scale) / 2;
+		const contentX = clientX - rect.left - offsetX;
+		const contentY = clientY - rect.top - offsetY;
+		return {
+			x: contentX / scale + layout.x,
+			y: contentY / scale + layout.y
+		};
+	};
+	let disposed = false;
+	/**
+	* canvas 水合：把 handler 经 hitTest 定位绑到 `<canvas>`
+	* @description canvas 无逐图元 DOM，`locate(event)` = client 坐标经 `clientToScene` 逆 meet-fit 成 Scene 点
+	*   （落 letterbox 黑边 → null、不命中），再 `hitTest(currentScene, point, { context2d })` 返回命中图元 id。
+	*   `context2d` 用 canvas 自己的 2D context（生产真实；测试 spy 的 harness context 经 `getContext('2d')` 返回）
+	*   作几何重建 + 原生点测的载体。绑定经 `createHydrationController`（根级委托 + enter/leave 合成 + dispose）。
+	*/
+	const hydrate = (hydrateOptions) => {
+		const context2d = canvas.getContext("2d") ?? void 0;
+		return { dispose: (0, _retikz_render_hydration.createHydrationController)(canvas, hydrateOptions.handlers, (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 };
+	};
+	return {
+		root: canvas,
+		update(next) {
+			if (disposed) throw new Error("mountCanvas: view already disposed.");
+			renderInto(next);
+		},
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			canvas.remove();
+		},
+		hydrate,
+		clientToScene
+	};
+};
+//#endregion
+exports.mountCanvas = mountCanvas;

package/dist/lib/mountCanvas.d.ts

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

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

@@ -0,0 +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"}

package/dist/lib/types.d.ts

@@ -1,4 +1,5 @@
 import { CompileOptions, IR, Scene } from '@retikz/core';
+import { HydrationHandlers } from '@retikz/render/hydration';
 import { Figure } from './figure';
 /** mountSvg / renderToSvgString 的入参：已编译 `Scene`、待编译 `IR`，或命令式 builder 的 `Figure` */
 export type RenderInput = Scene | IR | Figure;
@@ -25,4 +26,47 @@ export type VanillaView = {
     /** 卸载：移除 `root`、置 view 失效（再调 `update` 抛、`dispose` noop） */
     dispose: () => void;
 };
+/** `hydrate` / `view.hydrate` 返回的解绑句柄 */
+export type HydrationHandle = {
+    /** 解绑本次水合的全部 listener，之后事件不再触发 */
+    dispose: () => void;
+};
+/** 水合入参：按 id 提供的 handler 注册表（事件名 → handler） */
+export type HydrateOptions = {
+    /** id → 事件名 → handler 的注册表（透传给 `@retikz/render/hydration` 控制器） */
+    handlers: HydrationHandlers;
+};
+/** Scene user units 坐标点（hitTest 入参 / 坐标映射出参） */
+export type ScenePoint = {
+    /** Scene user units 横坐标 */
+    x: number;
+    /** Scene user units 纵坐标 */
+    y: number;
+};
+/**
+ * `mountCanvas` 返回的句柄：在 `VanillaView` 基础上加 canvas 侧水合 + 坐标映射
+ * @description `root` 是挂出的 `<canvas>`（非 svg），与 `mountSvg` 的 `<svg>` 对应；`hydrate` 用 `hitTest` +
+ *   client→Scene 坐标映射做定位；`clientToScene` 把指针的 client 像素逆 meet-fit 映射回 Scene user units（供 hitTest）。
+ */
+export type CanvasView = {
+    /** 挂载出的 `<canvas>`；跨 `update` 同一元素（不被替换） */
+    readonly root: HTMLCanvasElement;
+    /** 整图重渲染（原地复用 `root`、重设位图尺寸 + 重绘），不承诺局部 patch */
+    update: (next: RenderInput) => void;
+    /** 卸载：移除 `root`、解绑水合、置 view 失效（再调 `update` 抛、`dispose` noop） */
+    dispose: () => void;
+    /** 绑定 handler：以 `hitTest` + `clientToScene` 构造 `locate`，经 `createHydrationController` 委托 */
+    hydrate: (options: HydrateOptions) => HydrationHandle;
+    /**
+     * 把指针的 client 像素坐标逆 meet-fit 映射成 Scene user units（命中映射用）
+     * @description 始终返回逆 fit 后的 Scene 点；落在 letterbox 黑边外的点会得到 layout 区域外坐标，
+     *   交给 `hitTest` 自然判为无命中（无需在此截断），故无 `null` 返回。
+     */
+    clientToScene: (clientX: number, clientY: number) => ScenePoint;
+};
+/** `mountCanvas` 选项：继承 SSR / compile 公共项，外加 canvas 显示 / dpr 透传 */
+export type MountCanvasOptions = CommonOptions & {
+    /** 设备像素比；缺省读 `globalThis.devicePixelRatio`、再回退 1（镜像 react CanvasHost） */
+    devicePixelRatio?: number;
+};
 //# 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,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"}
+{"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retikz/vanilla",
-  "version": "0.3.0-alpha.2",
+  "version": "0.3.0-alpha.3",
   "description": "Framework-free runtime for retikz: mount Scene/IR to SVG DOM, or render to SVG string for SSR.",
   "type": "module",
   "author": "Pionpill",
@@ -39,8 +39,8 @@
     "dist/**/*"
   ],
   "dependencies": {
-    "@retikz/render": "0.3.0-alpha.2",
-    "@retikz/core": "0.3.0-alpha.2"
+    "@retikz/core": "0.3.0-alpha.3",
+    "@retikz/render": "0.3.0-alpha.3"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",