@sketch-ruler/core 3.0.0-beta.0

package/AGENTS.md

@@ -0,0 +1,145 @@
+# @sketch-ruler/core 项目指南
+
+> 本文件面向 AI Coding Agent，用于快速理解 `@sketch-ruler/core` 的结构、API 与开发约定。
+
+---
+
+## 包概述
+
+`@sketch-ruler/core` 是 **框架无关** 的核心层，零外部依赖。负责：
+
+- 坐标变换引擎（TransformEngine）
+- 矩阵运算与坐标转换
+- 刻度计算与配置
+- 参考线状态管理（LineManager）
+- 多画布管理器（CanvasManager）
+- 插件系统（PluginManager）
+- 吸附引擎（SnapEngine）
+- Minimap 引擎（MinimapEngine）
+
+---
+
+## 目录结构
+
+```
+src/
+├── engine/           # 变换引擎、矩阵、坐标转换、Minimap 引擎
+│   ├── transform-engine.ts
+│   ├── matrix.ts
+│   ├── coordinate.ts
+│   ├── minimap-engine.ts
+│   └── index.ts
+├── state/            # 状态管理（RulerState、LineManager）
+│   ├── ruler-state.ts
+│   ├── line-manager.ts
+│   └── index.ts
+├── managers/         # 多画布管理器
+│   └── canvas-manager.ts
+├── plugins/          # 插件系统
+│   ├── plugin-manager.ts
+│   └── index.ts
+├── scale/            # 刻度计算
+│   ├── tick-config.ts
+│   └── index.ts
+├── snap/             # 吸附引擎
+│   └── snap-engine.ts
+├── types/            # 框架无关的纯类型定义
+│   └── index.ts
+├── utils/            # ID 生成、线段工具函数
+│   ├── id-utils.ts
+│   └── line-utils.ts
+└── index.ts          # 统一导出入口
+```
+
+---
+
+## 构建与测试
+
+```bash
+# 安装依赖（在根目录执行）
+pnpm i
+
+# 构建本包
+cd packages/core && pnpm build
+
+# 运行测试
+cd packages/core && pnpm test
+
+# 测试监听模式
+cd packages/core && pnpm test:watch
+```
+
+---
+
+## 编码约定
+
+- **语言**：TypeScript 5.9+，strict 模式
+- **模块**：ESM（`"type": "module"`）
+- **DOM 依赖**：引擎层（`engine/`）**禁止**直接操作 DOM；DOM 相关逻辑由 `@sketch-ruler/canvas` 处理
+- **命名**：
+  - 类名：PascalCase（`TransformEngine`、`CanvasManager`）
+  - 类型/接口：PascalCase，以 `Type` 或 `Options` 结尾（`TransformState`、`TransformEngineOptions`）
+  - 纯工具函数：camelCase（`importLines`、`exportLines`）
+- **导出风格**：`index.ts` 按模块分类导出，类型与实现分离（`export` / `export type`）
+
+---
+
+## 关键 API 速查
+
+### TransformEngine
+
+```ts
+const engine = new TransformEngine(
+  { x: 0, y: 0, scale: 1 },
+  { minZoom: 0.1, maxZoom: 10, enableAnimation: true, animationMode: 'ease-out' }
+)
+engine.onUpdate((state) => { ... })   // 订阅状态
+engine.zoomBy(dScale, originX, originY) // 相对缩放
+engine.zoomTo(scale, originX, originY)  // 绝对缩放
+engine.panBy(dx, dy)                    // 相对平移
+engine.setTransform({ scale, x, y })    // 直接设置
+engine.destroy()
+```
+
+### CanvasManager
+
+```ts
+const manager = new CanvasManager([...])
+manager.onUpdate((state) => { ... })
+manager.addCanvas(config)
+manager.switchCanvas(id)
+manager.removeCanvas(id)
+manager.updateCanvasState(id, { scale, offsetX, offsetY })
+manager.updateCanvasLines(id, importLines({ h, v }))
+```
+
+### 参考线格式转换
+
+- `importLines({ h, v })` — `{h, v}` → `GuideLine[]`
+- `exportLines(guideLines)` — `GuideLine[]` → `{h, v}`
+
+### 矩阵与坐标
+
+- `fromTransform(scale, x, y)` → `Matrix6`
+- `toWorldPoint(matrix, screenX, screenY)` — 屏幕 → 世界
+- `toScreenPoint(matrix, worldX, worldY)` — 世界 → 屏幕
+
+---
+
+## 子路径导出
+
+| 路径 | 用途 |
+|------|------|
+| `@sketch-ruler/core` | 完整导出 |
+| `@sketch-ruler/core/engine` | 仅引擎层（TransformEngine、矩阵、坐标） |
+| `@sketch-ruler/core/state` | 仅状态管理 |
+| `@sketch-ruler/core/plugins` | 仅插件系统 |
+| `@sketch-ruler/core/scale` | 仅刻度计算 |
+
+---
+
+## 注意事项
+
+- `TransformEngine` 的所有坐标计算基于 **左上角原点** (`0, 0`)，外部 CSS 需要配合 `transform-origin: 0 0`
+- `CanvasManager` 的 `lines` 字段存储的是内部 `GuideLine[]` 格式，与 SketchRuler 组件的 `{h, v}` 格式需通过 `importLines` / `exportLines` 转换
+- 新增模块时，请在 `src/index.ts` 中按分类添加导出

package/README.md

@@ -0,0 +1,230 @@
+# @sketch-ruler/core
+
+> 框架无关的核心层：坐标变换引擎、多画布管理、参考线状态、吸附引擎、Minimap 引擎、刻度计算等。零外部依赖。
+
+## 安装
+
+```bash
+npm install @sketch-ruler/core
+# 或
+pnpm add @sketch-ruler/core
+```
+
+## 快速上手
+
+### TransformEngine — 2D 变换引擎
+
+维护缩放/平移状态，内置多种动画插值模式。
+
+```ts
+import { TransformEngine } from '@sketch-ruler/core'
+
+const engine = new TransformEngine(
+  { x: 0, y: 0, scale: 1 },           // 初始状态
+  { minZoom: 0.1, maxZoom: 10, enableAnimation: true, animationMode: 'ease-out' }
+)
+
+// 监听状态变化（注册时立即回调一次当前状态）
+const unsubscribe = engine.onUpdate((state) => {
+  console.log('scale', state.scale, 'offset', state.x, state.y)
+})
+
+// 以屏幕坐标 (400, 300) 为原点放大 0.5
+engine.zoomBy(0.5, 400, 300)
+
+// 缩放到指定比例
+engine.zoomTo(2, 400, 300)
+
+// 平移
+engine.panBy(100, -50)
+
+// 直接设置
+engine.setTransform({ scale: 1, x: 0, y: 0 })
+
+// 坐标转换
+const world = engine.toWorldPoint(100, 100)   // 屏幕 → 世界
+const screen = engine.toScreenPoint(50, 50)   // 世界 → 屏幕
+
+// 清理
+unsubscribe()
+engine.destroy()
+```
+
+### CanvasManager — 多画布管理器
+
+管理多个画布配置，支持模板、切换、导入导出。
+
+```ts
+import { CanvasManager, BUILTIN_TEMPLATES, exportLines, importLines } from '@sketch-ruler/core'
+
+const manager = new CanvasManager([
+  { name: '首页', width: 1920, height: 1080, lines: { h: [100], v: [200] } },
+  { name: '详情页', width: 375, height: 812 }
+])
+
+// 监听状态变化
+manager.onUpdate((state) => {
+  console.log('当前画布:', state.activeId, '总数:', state.canvases.length)
+})
+
+// 应用内置模板
+const id = manager.applyTemplate('A4 Portrait')
+
+// 切换画布（自动保存缩略图）
+manager.switchCanvas(id)
+
+// 更新当前画布的缩放与偏移
+manager.updateCanvasState(id, { scale: 0.8, offsetX: 100, offsetY: 50 })
+
+// 更新参考线（SketchRuler 发出的是 {h, v}，需先 importLines）
+manager.updateCanvasLines(id, importLines({ h: [0, 250], v: [0, 500] }))
+
+// 导出参考线（转回 {h, v} 给 SketchRuler）
+const canvas = manager.activeCanvas
+if (canvas) {
+  const lines = exportLines(canvas.lines) // => { h: number[], v: number[] }
+}
+
+// 删除画布
+manager.removeCanvas(id)
+```
+
+### 插件系统 — PluginManager
+
+```ts
+import { PluginManager } from '@sketch-ruler/core'
+import type { SketchRulerPlugin } from '@sketch-ruler/core'
+
+const pluginManager = new PluginManager()
+
+const myPlugin: SketchRulerPlugin = {
+  name: 'logger',
+  beforeZoom: (ctx) => {
+    console.log('zoom from', ctx.from, 'to', ctx.to)
+    return true // return false 可阻止缩放
+  },
+  onLineCreate: (ctx) => console.log('line created', ctx.line.id),
+  onLineDelete: (ctx) => console.log('line deleted', ctx.line.id)
+}
+
+pluginManager.register(myPlugin)
+```
+
+### 吸附引擎 — SnapEngine
+
+```ts
+import { SnapEngine } from '@sketch-ruler/core'
+
+const snapEngine = new SnapEngine({ threshold: 5 })
+
+const result = snapEngine.snap({
+  x: 102,
+  y: 198,
+  targets: [
+    { type: 'line', orientation: 'h', value: 100 },
+    { type: 'line', orientation: 'v', value: 200 }
+  ]
+})
+
+if (result.snapped) {
+  console.log('吸附到', result.x, result.y)
+}
+```
+
+### MinimapEngine — 缩略图导航引擎
+
+```ts
+import { MinimapEngine, MinimapDragSession } from '@sketch-ruler/core'
+
+const engine = new MinimapEngine({
+  contentWidth: 1920,
+  contentHeight: 1080,
+  viewportWidth: 1470,
+  viewportHeight: 700
+})
+
+// 更新视口状态
+engine.updateViewport({ x: 100, y: 50, scale: 0.5 })
+
+// 计算视口在缩略图中的矩形
+const rect = engine.getViewportRect(200, 150)
+
+// 拖拽会话
+const session = engine.startDrag(50, 50)
+const newPos = session.move(60, 60)
+engine.endDrag()
+```
+
+### 参考线工具函数
+
+```ts
+import { importLines, exportLines, computeLineStyle } from '@sketch-ruler/core'
+import type { GuideLine } from '@sketch-ruler/core'
+
+// SketchRuler {h, v} → 内部 GuideLine[]
+const guideLines: GuideLine[] = importLines({ h: [0, 250], v: [0, 500] })
+
+// 内部 GuideLine[] → SketchRuler {h, v}
+const lines = exportLines(guideLines) // { h: [0, 250], v: [0, 500] }
+
+// 计算参考线在 DOM 中的样式
+const style = computeLineStyle(guideLines[0], 1, 0, false, '#51d6a9')
+```
+
+### 矩阵与坐标工具
+
+```ts
+import {
+  createMatrix, fromTransform, multiply, invert, toCSSString,
+  toWorldPoint, toScreenPoint, fitRect
+} from '@sketch-ruler/core'
+
+// 从变换状态生成矩阵
+const matrix = fromTransform(1.5, 100, 50)
+
+// 转 CSS matrix 字符串
+const css = toCSSString(matrix) // "matrix(1.5, 0, 0, 1.5, 100, 50)"
+
+// 屏幕坐标 → 世界坐标
+const world = toWorldPoint(matrix, 200, 200)
+
+// 将内容矩形适配到视口
+const fitted = fitRect({ width: 1920, height: 1080 }, { width: 1470, height: 700 }, 0.2)
+```
+
+### 刻度计算
+
+```ts
+import { computeScaleMarks, getTickConfig, applyHysteresis } from '@sketch-ruler/core'
+
+const marks = computeScaleMarks({
+  scale: 1,
+  offset: 0,
+  length: 800,
+  thick: 20,
+  config: getTickConfig(1)
+})
+
+// 应用滞回避免频繁跳变
+const stableConfig = applyHysteresis(0.85, getTickConfig(0.8), getTickConfig(1))
+```
+
+## API 概览
+
+| 模块 | 导出 | 说明 |
+|------|------|------|
+| `TransformEngine` | 类 | 2D 仿射变换引擎，支持动画 |
+| `CanvasManager` | 类 | 多画布生命周期管理 |
+| `BUILTIN_TEMPLATES` | 常量 | 内置画布模板（A4、Web 1920、Mobile 等） |
+| `PluginManager` | 类 | 插件注册与生命周期调度 |
+| `SnapEngine` | 类 | 参考线吸附计算 |
+| `MinimapEngine` | 类 | 缩略图视口映射与拖拽 |
+| `LineManager` | 类 | 参考线增删改查 |
+| `importLines` / `exportLines` | 函数 | 参考线格式转换 |
+| `computeLineStyle` | 函数 | 参考线 DOM 样式计算 |
+| `computeScaleMarks` | 函数 | 刻度标记计算 |
+| `fromTransform` / `toWorldPoint` / `toScreenPoint` | 函数 | 矩阵与坐标转换 |
+
+## License
+
+MIT

package/lib/engine/coordinate.d.ts

@@ -0,0 +1,38 @@
+import { Matrix6 } from './matrix';
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * 屏幕坐标 → 世界坐标
+ */
+export declare function toWorldPoint(matrix: Matrix6, screenX: number, screenY: number): Point;
+/**
+ * 世界坐标 → 屏幕坐标
+ */
+export declare function toScreenPoint(matrix: Matrix6, worldX: number, worldY: number): Point;
+/**
+ * 批量屏幕坐标 → 世界坐标
+ */
+export declare function batchToWorld(matrix: Matrix6, points: Point[]): Point[];
+/**
+ * 批量世界坐标 → 屏幕坐标
+ */
+export declare function batchToScreen(matrix: Matrix6, points: Point[]): Point[];
+/**
+ * Fit 矩形到目标矩形
+ * @param mode 'contain' | 'cover' | 'center'
+ * @param paddingRatio 边距比例（默认 0，即不留边距）
+ */
+export declare function fitRect(source: Rect, target: Rect, mode?: 'contain' | 'cover' | 'center', paddingRatio?: number): {
+    scale: number;
+    x: number;
+    y: number;
+};
+//# sourceMappingURL=coordinate.d.ts.map

package/lib/engine/coordinate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinate.d.ts","sourceRoot":"","sources":["../../src/engine/coordinate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAEvC,MAAM,WAAW,KAAK;IACpB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV;AAED,MAAM,WAAW,IAAI;IACnB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CAcrF;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAKpF;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAEtE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAEvE;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,IAAI,EACZ,MAAM,EAAE,IAAI,EACZ,IAAI,GAAE,SAAS,GAAG,OAAO,GAAG,QAAoB,EAChD,YAAY,SAAI,GACf;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CA4BzC"}

package/lib/engine/index.d.ts

@@ -0,0 +1,7 @@
+export { createMatrix, fromTransform, multiply, invert, decompose, toCSSString, equals } from './matrix';
+export type { Matrix6 } from './matrix';
+export { toWorldPoint, toScreenPoint, batchToWorld, batchToScreen, fitRect } from './coordinate';
+export type { Point, Rect } from './coordinate';
+export { TransformEngine } from './transform-engine';
+export type { TransformState, TransformEngineOptions, TransformUpdateCallback } from './transform-engine';
+//# sourceMappingURL=index.d.ts.map

package/lib/engine/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,MAAM,EACN,SAAS,EACT,WAAW,EACX,MAAM,EACP,MAAM,UAAU,CAAA;AACjB,YAAY,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAEvC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAChG,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AAE/C,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACpD,YAAY,EACV,cAAc,EACd,sBAAsB,EACtB,uBAAuB,EACxB,MAAM,oBAAoB,CAAA"}

package/lib/engine/matrix.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 2D 仿射变换矩阵运算
+ * 使用 Float64Array(6) 紧凑存储: [a, b, c, d, e, f]
+ * 对应变换矩阵:
+ *   | a  c  e |
+ *   | b  d  f |
+ *   | 0  0  1 |
+ *
+ * 零 DOM 依赖，纯数学运算，可在 Node.js 环境直接测试
+ */
+export type Matrix6 = Float64Array;
+/**
+ * 创建单位矩阵
+ */
+export declare function createMatrix(): Matrix6;
+/**
+ * 从缩放和平移参数创建矩阵
+ */
+export declare function fromTransform(scale: number, x: number, y: number): Matrix6;
+/**
+ * 矩阵乘法: result = a * b
+ */
+export declare function multiply(a: Matrix6, b: Matrix6): Matrix6;
+/**
+ * 求逆矩阵
+ */
+export declare function invert(m: Matrix6): Matrix6 | null;
+/**
+ * 分解矩阵为 scale, x, y
+ * 假设无旋转和倾斜（sketch-ruler 场景）
+ */
+export declare function decompose(m: Matrix6): {
+    scale: number;
+    translateX: number;
+    translateY: number;
+};
+/**
+ * 转换为 CSS transform string
+ */
+export declare function toCSSString(m: Matrix6): string;
+/**
+ * 判断两个矩阵是否相等（考虑浮点误差）
+ */
+export declare function equals(a: Matrix6, b: Matrix6, epsilon?: number): boolean;
+//# sourceMappingURL=matrix.d.ts.map

package/lib/engine/matrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix.d.ts","sourceRoot":"","sources":["../../src/engine/matrix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,MAAM,OAAO,GAAG,YAAY,CAAA;AAElC;;GAEG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAE1E;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CASxD;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAejD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAM/F;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAE9C;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,SAAO,GAAG,OAAO,CAOtE"}

package/lib/engine/minimap-engine.d.ts

@@ -0,0 +1,64 @@
+export interface MinimapOptions {
+    contentWidth: number;
+    contentHeight: number;
+    viewportX: number;
+    viewportY: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    scale: number;
+    width: number;
+    height: number;
+}
+export interface MinimapState {
+    miniScale: number;
+    contentOffset: {
+        x: number;
+        y: number;
+    };
+    viewportRect: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+}
+export interface DragSessionState {
+    targetX: number;
+    targetY: number;
+    dragRect: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+}
+export declare class MinimapEngine {
+    private options;
+    constructor(options: MinimapOptions);
+    getState(): MinimapState;
+    clampTransform(x: number, y: number): {
+        x: number;
+        y: number;
+    };
+    canPan(): boolean;
+    clickAt(clientX: number, clientY: number, rectLeft: number, rectTop: number): {
+        x: number;
+        y: number;
+    };
+    startDrag(startViewportX: number, startViewportY: number, startMinimapLeft: number, startMinimapTop: number): MinimapDragSession;
+}
+export declare class MinimapDragSession {
+    private engine;
+    private startViewportX;
+    private startViewportY;
+    private startMinimapLeft;
+    private startMinimapTop;
+    private ratio;
+    constructor(engine: MinimapEngine, startViewportX: number, startViewportY: number, startMinimapLeft: number, startMinimapTop: number);
+    move(accDx: number, accDy: number): DragSessionState;
+    end(accDx: number, accDy: number): {
+        x: number;
+        y: number;
+    };
+}
+//# sourceMappingURL=minimap-engine.d.ts.map

package/lib/engine/minimap-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"minimap-engine.d.ts","sourceRoot":"","sources":["../../src/engine/minimap-engine.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,cAAc,EAAE,MAAM,CAAA;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACvC,YAAY,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;CAC3E;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;CACvE;AAED,qBAAa,aAAa;IACZ,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAE3C,QAAQ,IAAI,YAAY;IAsBxB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE;IAsB9D,MAAM,IAAI,OAAO;IAOjB,OAAO,CACL,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE;IAS3B,SAAS,CACP,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM,EACtB,gBAAgB,EAAE,MAAM,EACxB,eAAe,EAAE,MAAM,GACtB,kBAAkB;CAStB;AAED,qBAAa,kBAAkB;IAI3B,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,cAAc;IACtB,OAAO,CAAC,cAAc;IACtB,OAAO,CAAC,gBAAgB;IACxB,OAAO,CAAC,eAAe;IAPzB,OAAO,CAAC,KAAK,CAAQ;gBAGX,MAAM,EAAE,aAAa,EACrB,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM,EACtB,gBAAgB,EAAE,MAAM,EACxB,eAAe,EAAE,MAAM;IAKjC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,gBAAgB;IAsBpD,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE;CAM5D"}

package/lib/engine/transform-engine.d.ts

@@ -0,0 +1,78 @@
+import { Matrix6 } from './matrix';
+export interface TransformState {
+    x: number;
+    y: number;
+    scale: number;
+}
+export type AnimationMode = 'direct' | 'ease-out' | 'damped' | 'exponential';
+export interface TransformEngineOptions {
+    minZoom?: number;
+    maxZoom?: number;
+    enableAnimation?: boolean;
+    animationDuration?: number;
+    animationMode?: AnimationMode;
+    /** 阻尼系数（damped 模式），默认 0.8 */
+    dampingRatio?: number;
+    /** 自然频率 rad/s（damped 模式），默认 20 */
+    naturalFrequency?: number;
+    /** 时间常数 ms（exponential 模式），默认 80 */
+    timeConstant?: number;
+}
+export type TransformUpdateCallback = (state: TransformState) => void;
+export declare class TransformEngine {
+    private matrix;
+    private targetState;
+    private currentState;
+    private minZoom;
+    private maxZoom;
+    private enableAnimation;
+    private animationDuration;
+    private animationMode;
+    private dampingRatio;
+    private naturalFrequency;
+    private timeConstant;
+    private pendingTransform;
+    private rafId;
+    private callbacks;
+    private lastFrameTime;
+    private velocity;
+    constructor(initial?: TransformState, options?: TransformEngineOptions);
+    /** 注册更新回调 */
+    onUpdate(callback: TransformUpdateCallback): () => void;
+    /** 原子性设置变换状态 */
+    setTransform(t: Partial<TransformState>): void;
+    /** 相对平移 */
+    panBy(dx: number, dy: number): void;
+    /**
+     * 以指定原点为中心缩放
+     * @param dScale 缩放增量（相对当前 scale）
+     * @param originX 缩放原点屏幕坐标 X
+     * @param originY 缩放原点屏幕坐标 Y
+     */
+    zoomBy(dScale: number, originX: number, originY: number): void;
+    /** 缩放至目标比例 */
+    zoomTo(scale: number, originX: number, originY: number): void;
+    /** 屏幕坐标 → 世界坐标 */
+    toWorldPoint(screenX: number, screenY: number): {
+        x: number;
+        y: number;
+    };
+    /** 世界坐标 → 屏幕坐标 */
+    toScreenPoint(worldX: number, worldY: number): {
+        x: number;
+        y: number;
+    };
+    /** 获取当前状态 */
+    getState(): TransformState;
+    /** 获取当前变换矩阵 */
+    getMatrix(): Matrix6;
+    /** 销毁引擎，清理资源 */
+    destroy(): void;
+    private clampScale;
+    private updateMatrix;
+    private scheduleUpdate;
+    private onFrame;
+    private lerp;
+    private notify;
+}
+//# sourceMappingURL=transform-engine.d.ts.map

package/lib/engine/transform-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform-engine.d.ts","sourceRoot":"","sources":["../../src/engine/transform-engine.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAiD,KAAK,OAAO,EAAE,MAAM,UAAU,CAAA;AAGtF,MAAM,WAAW,cAAc;IAC7B,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,aAAa,CAAA;AAE5E,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B,6BAA6B;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,kCAAkC;IAClC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,oCAAoC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,MAAM,uBAAuB,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAA;AAErE,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,iBAAiB,CAAQ;IACjC,OAAO,CAAC,aAAa,CAAe;IACpC,OAAO,CAAC,YAAY,CAAQ;IAC5B,OAAO,CAAC,gBAAgB,CAAQ;IAChC,OAAO,CAAC,YAAY,CAAQ;IAE5B,OAAO,CAAC,gBAAgB,CAAQ;IAChC,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,SAAS,CAA0C;IAE3D,OAAO,CAAC,aAAa,CAAI;IAEzB,OAAO,CAAC,QAAQ,CAA2B;gBAGzC,OAAO,GAAE,cAAyC,EAClD,OAAO,GAAE,sBAA2B;IAiBtC,aAAa;IACb,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,GAAG,MAAM,IAAI;IASvD,gBAAgB;IAChB,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI;IAoB9C,WAAW;IACX,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAanC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAyB9D,cAAc;IACd,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAK7D,kBAAkB;IAClB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE;IAIxE,kBAAkB;IAClB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE;IAIvE,aAAa;IACb,QAAQ,IAAI,cAAc;IAI1B,eAAe;IACf,SAAS,IAAI,OAAO;IAIpB,gBAAgB;IAChB,OAAO,IAAI,IAAI;IAQf,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,OAAO;IA+Ff,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,MAAM;CAIf"}