u-space 0.0.1 → 0.0.3

package/dist/plugins/topology-drawer/index.js

@@ -0,0 +1,182 @@
+import { PlaneGeometry as n, Mesh as r, MeshBasicNodeMaterial as h, BufferGeometry as a, Float32BufferAttribute as l, Line as p, LineBasicNodeMaterial as _ } from "three/webgpu";
+import { Topology as v } from "u-space";
+class u {
+  viewer;
+  topology;
+  _snapRadius;
+  // Typed reference to viewer.scene for InteractionEventMap listeners
+  _scene;
+  // Invisible ground plane added to scene as raycast fallback for empty space
+  _groundMesh;
+  _previewLine;
+  _previewGeometry;
+  _lastNodeId = null;
+  _nodeCounter = 0;
+  _history = [];
+  _enabled = !1;
+  _prevFrameloop = "demand";
+  _prevPointerMoveEnabled = !1;
+  constructor(e, t) {
+    this.viewer = e, this._snapRadius = t?.snapRadius ?? 1, this._scene = e.scene, this.topology = new v({
+      nodeColor: t?.nodeColor,
+      nodeRadius: t?.nodeRadius,
+      edgeColor: t?.edgeColor,
+      edgeRadius: t?.edgeRadius,
+      pathColor: t?.pathColor,
+      pathRadius: t?.pathRadius
+    });
+    const o = new n(1e5, 1e5);
+    o.rotateX(-Math.PI / 2), this._groundMesh = new r(o, new h({ visible: !1 })), this._groundMesh.position.y = t?.groundY ?? 0, this._previewGeometry = new a(), this._previewGeometry.setAttribute("position", new l(new Float32Array(6), 3)), this._previewLine = new p(
+      this._previewGeometry,
+      new _({ color: t?.previewColor ?? 16776960, depthTest: !1 })
+    ), this._previewLine.renderOrder = 10, this._previewLine.visible = !1;
+  }
+  // ─── Private helpers ──────────────────────────────────────────────────────
+  _findNearestNode(e) {
+    let t = this._snapRadius, o = null;
+    return this.topology.nodes.forEach((i, s) => {
+      const d = e.distanceTo(i);
+      d < t && (t = d, o = s);
+    }), o;
+  }
+  _setPreviewLine(e, t) {
+    const o = this._previewGeometry.attributes.position;
+    o.setXYZ(0, e.x, e.y, e.z), o.setXYZ(1, t.x, t.y, t.z), o.needsUpdate = !0, this._previewLine.visible = !0;
+  }
+  /**
+   * Resolve the world-space placement point from an InteractionEvent.
+   *
+   * - If the original hit was a topology node, return its registered position
+   *   (more accurate than the sphere surface point).
+   * - If the hit was a topology edge, return the surface hit point so a new
+   *   node can be inserted at that location and connected.
+   * - Otherwise use intersect.point directly.
+   */
+  _resolvePoint(e) {
+    const t = e.intersect?.point;
+    if (!t) return null;
+    const { type: o, id: i } = e.target.userData;
+    return o === "node" && i ? this.topology.nodes.get(i)?.clone() ?? t.clone() : t.clone();
+  }
+  _placePoint(e) {
+    const t = this._findNearestNode(e);
+    if (t) {
+      this._lastNodeId && this._lastNodeId !== t && (this.topology.addEdge(this._lastNodeId, t), this._history.push({
+        type: "addEdge",
+        from: this._lastNodeId,
+        to: t,
+        prevLastNodeId: this._lastNodeId
+      }), this._lastNodeId = t, this.topology.renderGraph());
+      return;
+    }
+    const o = `node_${this._nodeCounter++}`;
+    this.topology.addNode(o, e);
+    const i = { type: "addNode", nodeId: o, prevLastNodeId: this._lastNodeId };
+    this._lastNodeId && (this.topology.addEdge(this._lastNodeId, o), i.addedEdge = { from: this._lastNodeId, to: o }), this._history.push(i), this._lastNodeId = o, this.topology.renderGraph();
+  }
+  /**
+   * Insert a new node into an existing edge (split it).
+   *
+   * The original edge (cutFrom ↔ cutTo) is removed and replaced with two
+   * edges: cutFrom → newNode → cutTo.
+   * If a path chain is active (_lastNodeId set, and different from the edge
+   * endpoints), an additional edge _lastNodeId → newNode is added.
+   */
+  _splitEdge(e, t, o, i) {
+    const s = `node_${this._nodeCounter++}`;
+    this.topology.addNode(s, e), this.topology.removeEdge(t, o), this.topology.addEdge(t, s), this.topology.addEdge(s, o);
+    const d = {
+      type: "splitEdge",
+      nodeId: s,
+      cutFrom: t,
+      cutTo: o,
+      cutWeight: i,
+      prevLastNodeId: this._lastNodeId
+    };
+    this._lastNodeId && this._lastNodeId !== t && this._lastNodeId !== o && (this.topology.addEdge(this._lastNodeId, s), d.chainEdge = { from: this._lastNodeId, to: s }), this._history.push(d), this._lastNodeId = s, this.topology.renderGraph();
+  }
+  // ─── Scene-level InteractionManager event handlers ────────────────────────
+  _onSceneClick = ({ event: e }) => {
+    const t = e.target.userData;
+    if (t.type === "edge" && t.from && t.to) {
+      const i = e.intersect?.point;
+      if (!i) return;
+      this._splitEdge(i.clone(), t.from, t.to, t.weight ?? 0);
+      return;
+    }
+    const o = this._resolvePoint(e);
+    o && this._placePoint(o);
+  };
+  _onScenePointerMove = ({ event: e }) => {
+    if (!this._lastNodeId) return;
+    const t = e.intersect?.point;
+    if (!t) return;
+    const o = this.topology.nodes.get(this._lastNodeId);
+    o && this._setPreviewLine(o, t);
+  };
+  _onSceneContextMenu = ({ event: e }) => {
+    e.originalEvent.preventDefault(), this.finishPath();
+  };
+  _onKeyDown = (e) => {
+    e.key === "Escape" ? this.finishPath() : (e.ctrlKey || e.metaKey) && e.key === "z" && (e.preventDefault(), this.undo());
+  };
+  // ─── Public API ───────────────────────────────────────────────────────────
+  /** Finish the current path chain. Next click starts an unconnected new path. */
+  finishPath() {
+    this._history.push({ type: "finishPath", prevLastNodeId: this._lastNodeId }), this._lastNodeId = null, this._previewLine.visible = !1;
+  }
+  /** Undo the last action (node, edge, or finishPath). */
+  undo() {
+    const e = this._history.pop();
+    if (e)
+      if (e.type === "addNode" ? (e.addedEdge && this.topology.removeEdge(e.addedEdge.from, e.addedEdge.to), this.topology.removeNode(e.nodeId), this._lastNodeId = e.prevLastNodeId, this.topology.renderGraph()) : e.type === "addEdge" ? (this.topology.removeEdge(e.from, e.to), this._lastNodeId = e.prevLastNodeId, this.topology.renderGraph()) : e.type === "splitEdge" ? (this.topology.removeEdge(e.cutFrom, e.nodeId), this.topology.removeEdge(e.nodeId, e.cutTo), e.chainEdge && this.topology.removeEdge(e.chainEdge.from, e.chainEdge.to), this.topology.removeNode(e.nodeId), this.topology.addEdge(e.cutFrom, e.cutTo, e.cutWeight), this._lastNodeId = e.prevLastNodeId, this.topology.renderGraph()) : e.type === "finishPath" && (this._lastNodeId = e.prevLastNodeId), this._lastNodeId) {
+        const t = this.topology.nodes.get(this._lastNodeId);
+        t && this._setPreviewLine(t, t);
+      } else
+        this._previewLine.visible = !1;
+  }
+  /** Remove all drawn nodes, edges, and path meshes. */
+  clear() {
+    this.topology.clearGraph(), this.topology.clearPaths(), this.topology.nodes.clear(), this.topology.adjacencyMap.clear(), this._lastNodeId = null, this._nodeCounter = 0, this._history = [], this._previewLine.visible = !1;
+  }
+  /** Export the current topology as a JSON-serializable object. Delegates to `topology.exportData()`. */
+  exportData() {
+    return this.topology.exportData();
+  }
+  /**
+   * Load a previously exported topology, replacing any current drawing.
+   * Delegates to `topology.importData()` and resets the drawer's internal node counter.
+   */
+  importData(e) {
+    this._lastNodeId = null, this._history = [], this._previewLine.visible = !1, this.topology.importData(e), Object.keys(e.nodes).forEach((t) => {
+      const o = parseInt(t.replace("node_", ""), 10);
+      !isNaN(o) && o >= this._nodeCounter && (this._nodeCounter = o + 1);
+    });
+  }
+  /**
+   * Enable drawing mode.
+   *
+   * - Adds the topology, preview line, and fallback ground plane to the scene.
+   * - Registers `click`, `pointermove`, `contextmenu` listeners on `viewer.scene`
+   *   (events are bubbled up by InteractionManager from whichever object is hit).
+   * - Enables `pointerMoveEventsEnabled` on the InteractionManager for the
+   *   preview line to track the cursor.
+   */
+  enable() {
+    return this._enabled ? this : (this._enabled = !0, this._prevFrameloop = this.viewer.frameloop, this._prevPointerMoveEnabled = this.viewer.interactionManager.pointerMoveEventsEnabled, this.viewer.frameloop = "always", this.viewer.interactionManager.pointerMoveEventsEnabled = !0, this.viewer.scene.add(this._groundMesh), this.viewer.scene.add(this.topology), this.viewer.scene.add(this._previewLine), this._scene.addEventListener("click", this._onSceneClick), this._scene.addEventListener("pointermove", this._onScenePointerMove), this._scene.addEventListener("rightclick", this._onSceneContextMenu), window.addEventListener("keydown", this._onKeyDown), this);
+  }
+  /**
+   * Disable drawing mode.
+   * The drawn topology remains visible in the scene.
+   */
+  disable() {
+    return this._enabled ? (this._enabled = !1, this.viewer.frameloop = this._prevFrameloop, this.viewer.interactionManager.pointerMoveEventsEnabled = this._prevPointerMoveEnabled, this.viewer.scene.remove(this._groundMesh), this.viewer.scene.remove(this._previewLine), this._previewLine.visible = !1, this._scene.removeEventListener("click", this._onSceneClick), this._scene.removeEventListener("pointermove", this._onScenePointerMove), this._scene.removeEventListener("rightclick", this._onSceneContextMenu), window.removeEventListener("keydown", this._onKeyDown), this) : this;
+  }
+  /** Fully dispose all resources and remove the topology from the scene. */
+  dispose() {
+    this.disable(), this.viewer.scene.remove(this.topology), this._groundMesh.geometry.dispose(), this._groundMesh.material.dispose(), this._previewGeometry.dispose(), this._previewLine.material.dispose(), this.topology.dispose();
+  }
+}
+export {
+  u as TopologyDrawer
+};

package/dist/src/interactions/InteractionEvent.d.ts

@@ -1,5 +1,5 @@
 import type { Object3D, Intersection, Object3DEventMap } from 'three/webgpu';
-export type InteractionEventType = 'click' | 'dblclick' | 'contextmenu' | 'pointerdown' | 'pointerup' | 'pointermove' | 'pointerenter' | 'pointerleave';
+export type InteractionEventType = 'click' | 'dblclick' | 'rightclick' | 'pointerdown' | 'pointerup' | 'pointermove' | 'pointerenter' | 'pointerleave';
 export interface InteractionEventParameters {
     type: InteractionEventType;
     target: Object3D<InteractionEventMap>;

package/dist/src/interactions/InteractionManager.d.ts

@@ -17,10 +17,9 @@ export declare class InteractionManager {
     private longPressThreshold;
     private moveThreshold;
     /**
-     * The objects to check for intersections.
-     * If not set, it defaults to the children of the scene.
+     * The objects to check for intersections. default to all children of the scene (including nested).
      */
-    targetObjects: Object3D<InteractionEventMap>[] | null;
+    targetObjects: Object3D<InteractionEventMap>[];
     /**
      * Whether to enable pointer move events (pointermove, pointerenter, pointerleave).
      * Disabled by default for performance optimization.

package/dist/src/objects/Topology.d.ts

@@ -1,7 +1,19 @@
-import { type Vector3, Group, type ColorRepresentation } from 'three/webgpu';
+import { Vector3, Group, type ColorRepresentation } from 'three/webgpu';
 import type { InteractionEventMap } from '../interactions';
 import { TubeMesh } from './TubeMesh';
 import { BaseGroup } from './BaseGroup';
+export type TopologyData = {
+    nodes: Record<string, {
+        x: number;
+        y: number;
+        z: number;
+    }>;
+    edges: Array<{
+        from: string;
+        to: string;
+        weight: number;
+    }>;
+};
 export interface TopologyParameters {
     nodeColor?: ColorRepresentation;
     nodeRadius?: number;
@@ -59,6 +71,13 @@ export declare class Topology extends BaseGroup<InteractionEventMap> {
      */
     renderPath(points: Vector3[], color?: ColorRepresentation): TubeMesh | undefined;
     clearPaths(): void;
+    /** Export nodes and edges as a JSON-serializable object. */
+    exportData(): TopologyData;
+    /**
+     * Load topology from a previously exported data object.
+     * Replaces all current nodes, edges, and path meshes, then re-renders the graph.
+     */
+    importData(data: TopologyData): void;
     dispose(): void;
     getNeighbors(id: string): Map<string, number> | undefined;
 }

package/docs/api-interactions.md

@@ -15,14 +15,14 @@ viewer.interactionManager.pointerMoveEventsEnabled = true;
 
 ### 目标对象
 
-可以限制射线检测所针对的对象范围。
+可以限制射线检测所针对的对象范围。默认值为 `scene.children`（即整个场景的直接子级，含递归嵌套）。
 
 ```typescript
-// 默认行为：检测整个场景
-viewer.interactionManager.targetObjects = [];
-
 // 仅检测指定对象
-// viewer.interactionManager.targetObjects = [myBox, myModel];
+viewer.interactionManager.targetObjects = [myBox, myModel];
+
+// 恢复默认：检测整个场景
+viewer.interactionManager.targetObjects = viewer.scene.children;
 ```
 
 ## 添加事件监听
@@ -48,7 +48,7 @@ myBox.addEventListener('click', (eventData) => {
 
 - `click`：指针点击对象时触发（过滤：长按或大幅移动后忽略）。
 - `dblclick`：快速双击对象时触发。
-- `contextmenu`：右键点击时触发（阻止默认浏览器上下文菜单）。
+- `rightclick`：右键短按松开时触发（长按或拖拽不触发；浏览器原生上下文菜单已被阻止）。与原生 `contextmenu` 的区别在于，此事件在 `pointerup` 时派发，因此可以正确过滤相机拖拽等操作。
 - `pointerdown`：指针按键在对象上按下时触发。
 - `pointerup`：指针按键在对象上释放时触发。
 - `pointermove`：指针在对象上移动时触发，需要 `pointerMoveEventsEnabled = true`。
@@ -91,7 +91,7 @@ myObject.addEventListener('click', (e) => {
 
 | 属性                       | 类型                          | 默认值  | 说明                                                       |
 | :------------------------- | :---------------------------- | :------ | :--------------------------------------------------------- |
-| `targetObjects`            | `Object3D[] \| null`          | `null`  | 射线检测的目标对象。`null` 表示检测所有场景子对象。        |
+| `targetObjects`            | `Object3D[]`                  | `scene.children` | 射线检测的目标对象列表，默认为场景的直接子级。  |
 | `pointerMoveEventsEnabled` | `boolean`                     | `false` | 启用 `pointermove`、`pointerenter`、`pointerleave` 事件。  |
 
 ### 方法

package/docs/api-objects.md

@@ -186,7 +186,9 @@ const poi = new Poi({
   backgroundColor: 'rgba(0,0,0,0.6)',
   textPosition: 'right',
 });
-await poi.updateAsync(); // 渲染 canvas 纹理
+// 构造时会自动调用 updateAsync()，无需手动调用
+// 如需更新参数，可再次调用：
+// await poi.updateAsync({ text: '新文字' });
 
 poi.position.set(10, 5, 10);
 viewer.scene.add(poi);
@@ -203,15 +205,16 @@ viewer.scene.add(poi);
 | `color`           | `string`                                    | `'#ffffff'`              | 文字颜色。                         |
 | `iconSize`        | `number`                                    | `64`                     | 图标大小（像素）。                 |
 | `padding`         | `number`                                    | `10`                     | 内容四周的内边距。                 |
-| `backgroundColor` | `string`                                    | `'rgba(0, 0, 0, 0.5)'`  | 背景填充颜色。                     |
+| `backgroundColor` | `string`                                    | `'rgba(0, 0, 0, 0)'`    | 背景填充颜色。                     |
 | `borderRadius`    | `number`                                    | `8`                      | 背景圆角半径。                     |
 | `textPosition`    | `'top' \| 'bottom' \| 'left' \| 'right'`   | `'right'`                | 文字相对图标的位置。               |
+| `scaleFactor`     | `number`                                    | `0.01`                   | canvas 像素到世界单位的缩放系数。  |
 
 ### 方法
 
 #### `updateAsync(parameters?)`
 
-使用可选的参数覆盖重新渲染 canvas 纹理。
+使用可选的参数覆盖重新渲染 canvas 纹理。构造时会自动调用一次，后续参数未变化时会跳过重绘。
 
 ```typescript
 await poi.updateAsync({ text: '更新后的标签', color: '#ffff00' });
@@ -306,6 +309,25 @@ viewer.render();
 
 返回节点的邻接表（邻居 ID → 边权重）。
 
+#### `exportData(): TopologyData`
+
+将当前拓扑图（节点和边）导出为 JSON 可序列化对象。
+
+```typescript
+const data = topo.exportData();
+// { nodes: Record<string, {x,y,z}>, edges: Array<{from,to,weight}> }
+```
+
+双向边在导出时会去重，只保留一条记录。
+
+#### `importData(data: TopologyData)`
+
+从 `exportData()` 返回的数据中还原拓扑图，替换当前所有节点、边和路径网格，并重新渲染。
+
+```typescript
+topo.importData(data);
+```
+
 #### `dispose()`
 
 清除图和路径网格。

package/docs/api-plugins.md

@@ -2,9 +2,7 @@
 
 `u-space` 架构包含一套丰富的插件，提供从 GIS 瓦片加载到键盘控制和场景管理等高级功能。所有插件从 `u-space/plugins/*` 命名空间导入。
 
-## 可用插件
-
-### `keyboard-controls`
+## `keyboard-controls`
 
 为激活相机提供 WASD 或方向键的平移和旋转控制。
 
@@ -45,7 +43,7 @@ import { ACTION } from 'u-space/plugins/keyboard-controls';
 keyboardControls.keys['Space'] = ACTION.MOVE_UP;
 ```
 
-### `minimap`
+## `minimap`
 
 生成一个 2D 小地图叠加层，在 3D 场景中跟踪目标对象。渲染到注入 `viewer.el` 的 `<canvas>` 元素中。
 
@@ -82,7 +80,7 @@ minimap.dispose();
 - `disable()` — 移除画布并停止渲染。
 - `dispose()` — 禁用并清理所有资源。
 
-### `tiles`
+## `tiles`
 
 提供与 `3d-tiles-renderer` 和地理空间数据的集成。主要导出 `ArcgisTilesRenderer`，可流式加载 ArcGIS Online 3D 瓦片并将地球重新定向到指定地理位置。
 
@@ -109,7 +107,7 @@ arcgisTilesRenderer.enable();
 | `disable()`                 | 从场景中移除瓦片并暂停更新循环。                                                               |
 | `dispose()`                 | 禁用并完全释放瓦片渲染器。                                                                     |
 
-### `u-manager`
+## `u-manager`
 
 `u-manager` 是一套全面的加载器和解析器，用于从服务器路径流式传输、解密并显示结构化场景数据。支持场景、拓扑、动画、属性和相机视点。
 
@@ -233,7 +231,7 @@ const modelProps = properties.filter(p => p.modelId === myModel.userData.id);
 | `value`   | `string \| null` | 属性值。                 |
 | `label`   | `string \| null` | 属性的显示标签。         |
 
-### `curve-movement`
+## `curve-movement`
 
 沿样条路径对相机或对象进行动画。提供两个具体子类：`CurveMovementCamera` 和 `CurveMovementObject`。
 
@@ -272,7 +270,7 @@ movement.addEventListener('complete', () => console.log('完成'));
 | `positionOffset`| `Vector3`                          | `(0,0,0)` | 叠加到每个位置上的世界坐标偏移量。   |
 | `direction`     | `1 \| -1`                          | `1`       | 当前行进方向。                       |
 
-### `tracking-controls`
+## `tracking-controls`
 
 使相机平滑跟随移动的 `Object3D` 目标。
 
@@ -296,7 +294,7 @@ tracking.enable();
 | `type`   | `'position' \| 'box3'` | `'position'` | 跟踪世界位置还是包围盒中心。                              |
 | `offset` | `Vector3`               | `(0,0,0)`    | 在移动相机前叠加到跟踪位置上的偏移量。                    |
 
-### `atmosphere`
+## `atmosphere`
 
 天空和大气渲染插件。目前为占位实现，`enable()` / `disable()` / `dispose()` 方法可用，但尚未实现具体功能。
 
@@ -306,3 +304,146 @@ import { Atmosphere } from 'u-space/plugins/atmosphere';
 const atmosphere = new Atmosphere(viewer);
 atmosphere.enable();
 ```
+
+## `object-controls`
+
+对场景中的 3D 对象进行交互式移动、旋转、缩放操作。继承自 Three.js `TransformControls`，集成了 u-space `Viewer` 生命周期管理。
+
+```typescript
+import { ObjectControls } from 'u-space/plugins/object-controls';
+
+const controls = new ObjectControls(viewer, {
+  mode: 'translate', // 'translate' | 'rotate' | 'scale'，默认 'translate'
+  space: 'world',    // 'world' | 'local'，默认 'world'
+  size: 1,           // 控件显示大小，默认 1
+});
+
+controls.enable();
+controls.attach(myMesh); // 将控件附加到目标对象
+
+// 切换模式（直接赋值，继承自 TransformControls）
+controls.mode = 'rotate';
+controls.space = 'local';
+
+// 监听变换事件
+controls.addEventListener('objectChange', () => {
+  console.log(myMesh.position);
+});
+
+controls.addEventListener('dragging-changed', ({ value }) => {
+  console.log('拖拽中：', value); // true = 开始，false = 结束
+});
+```
+
+**说明：**
+
+- `enable()` 时将 gizmo 加入场景并切换 `frameloop` 为 `'always'`，确保拖拽时连续渲染。
+- 拖拽期间自动挂起 `viewer.controls`（CameraControls）以避免冲突；`disable()` 时无论如何都强制还原相机控制，防止 mid-drag 调用 disable 导致相机卡死。
+- 监听 `viewer` 的 `cameraChange` 事件，`viewer.setCamera()` 切换相机后 gizmo 自动同步，无需手动更新。
+
+**构造选项（`ObjectControlsOptions`）：**
+
+| 选项     | 类型                               | 默认值        | 说明             |
+| :------- | :--------------------------------- | :------------ | :--------------- |
+| `mode`   | `'translate' \| 'rotate' \| 'scale'` | `'translate'` | 初始变换模式。   |
+| `space`  | `'world' \| 'local'`               | `'world'`     | 初始变换空间。   |
+| `size`   | `number`                           | `1`           | gizmo 大小。     |
+| `showX`  | `boolean`                          | `true`        | 显示 X 轴手柄。  |
+| `showY`  | `boolean`                          | `true`        | 显示 Y 轴手柄。  |
+| `showZ`  | `boolean`                          | `true`        | 显示 Z 轴手柄。  |
+
+**方法：**
+
+| 方法        | 说明                                                         |
+| :---------- | :----------------------------------------------------------- |
+| `enable()`  | 将 gizmo 加入场景，切换 frameloop 为 `'always'`。           |
+| `disable()` | 移除 gizmo，还原 frameloop 和 CameraControls。               |
+| `attach(object)` | 将控件附加到指定 Object3D。                             |
+| `detach()`  | 解除当前附加对象。                                           |
+| `dispose()` | 完全释放所有资源。                                           |
+
+**属性：**
+
+| 属性       | 类型      | 说明                                  |
+| :--------- | :-------- | :------------------------------------ |
+| `isActive` | `boolean` | 当前是否已调用 `enable()`（只读）。   |
+| `object`   | `Object3D \| undefined` | 当前附加的对象（继承自 TransformControls）。 |
+| `mode`     | `string`  | 当前变换模式，可直接赋值切换。        |
+| `space`    | `string`  | 当前变换空间，可直接赋值切换。        |
+
+> 由于 `ObjectControls` 直接继承 `TransformControls`，所有原生属性（`translationSnap`、`rotationSnap`、`scaleSnap`、`showX/Y/Z` 等）和事件均可直接使用，参考 [Three.js TransformControls 文档](https://threejs.org/docs/#examples/en/controls/TransformControls)。
+
+## `topology-drawer`
+
+在 3D 场景中交互式绘制拓扑路径图。点击场景中的任意对象表面放置节点，自动连接成路径；点击空白处则落回不可见的地面平面。事件检测通过 `viewer.interactionManager` 实现（`scene.addEventListener` 冒泡）。
+
+```typescript
+import { TopologyDrawer } from 'u-space/plugins/topology-drawer';
+
+const drawer = new TopologyDrawer(viewer, {
+  groundY: 0,       // 空白区域兜底地面的 Y 坐标，默认 0
+  snapRadius: 1.0,  // 自动吸附已有节点的世界单位半径，默认 1.0
+  nodeRadius: 0.3,
+  nodeColor: 0x0088ff,
+  edgeRadius: 0.1,
+  edgeColor: 0x00ddff,
+  previewColor: 0xffff00, // 预览线颜色
+});
+
+drawer.enable();
+```
+
+**操作说明：**
+
+| 操作 | 效果 |
+| :--- | :--- |
+| 左键点击空白 / 模型表面 | 放置新节点，与上一节点自动连边 |
+| 左键点击已有节点（`snapRadius` 范围内） | 吸附并连接到该节点，不新增节点 |
+| 左键点击已有边 | 切断该边，在点击处插入新节点并重连两端 |
+| 右键 / `Escape` | 结束当前路径链，下次点击开始新路径 |
+| `Ctrl / Cmd + Z` | 撤销最后一步（节点、边或结束路径） |
+
+**方法：**
+
+| 方法 | 说明 |
+| :--- | :--- |
+| `enable()` | 进入绘制模式，将拓扑与地面平面加入场景。同时自动将 `viewer.interactionManager.pointerMoveEventsEnabled` 置为 `true`（用于预览线跟随光标），并在 `disable()` 时恢复为原值。 |
+| `disable()` | 退出绘制模式，已绘内容仍保留在场景中。恢复 `pointerMoveEventsEnabled` 为调用 `enable()` 前的值。 |
+| `finishPath()` | 结束当前路径链（等同于右键 / Escape）。 |
+| `undo()` | 撤销最后一步操作。 |
+| `clear()` | 清空所有已绘节点、边和路径。 |
+| `exportData()` | 以 JSON 可序列化格式导出当前拓扑数据。 |
+| `importData(data)` | 加载 `exportData()` 返回的数据，替换当前内容。 |
+| `dispose()` | 完全释放所有资源并从场景移除拓扑。 |
+
+**属性：**
+
+| 属性 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `topology` | `Topology` | 底层 `Topology` 对象，可进一步访问节点、边和路径方法。 |
+
+**导出 / 导入：**
+
+```typescript
+// 导出
+const data = drawer.exportData();
+// data: { nodes: Record<string, {x,y,z}>, edges: Array<{from,to,weight}> }
+
+// 导入
+drawer.importData(data);
+```
+
+**结合 `SceneLoader` 在模型表面绘制：**
+
+```typescript
+import { SceneLoader } from 'u-space/plugins/u-manager';
+import { TopologyDrawer } from 'u-space/plugins/topology-drawer';
+
+const sceneLoader = new SceneLoader(viewer);
+sceneLoader.setPath('./scenes/my-scene');
+const group = await sceneLoader.loadAsync();
+viewer.scene.add(group);
+
+const drawer = new TopologyDrawer(viewer, { snapRadius: 1.0 });
+drawer.enable(); // 可直接在加载的模型表面点击绘制
+```

package/docs/api-viewer.md

@@ -100,6 +100,52 @@ const camera = viewer.createOrthographicCamera();
 viewer.setCamera(camera);
 ```
 
+## 调试工具
+
+### Info
+
+`viewer.info` 是一个轻量的渲染统计叠加层，显示当前帧的 GPU 诊断数据，适合开发调试阶段使用。
+
+```typescript
+viewer.info.enable();  // 在画面左下角显示统计信息
+viewer.info.disable(); // 隐藏统计信息
+```
+
+启用后将在 `viewer.el` 左下角叠加以下数据：
+
+| 指标           | 说明                          |
+| :------------- | :---------------------------- |
+| `draw calls`   | 当前帧的绘制调用次数          |
+| `frame calls`  | 当前帧的帧调用次数            |
+| `triangles`    | 当前帧渲染的三角面数量        |
+| `points`       | 当前帧渲染的点数量            |
+| `lines`        | 当前帧渲染的线段数量          |
+| `timestamp`    | GPU 渲染耗时（ms，WebGPU 专属）|
+
+> `timestamp` 指标仅在 WebGPU 后端可用，WebGL 回退模式下显示 `0`。
+
+### ViewerHelper
+
+`viewer.viewerHelper` 是一个方向指示器 gizmo（基于 Three.js `ViewHelper`），显示当前相机朝向的 XYZ 轴，渲染为画面角落的叠加层。
+
+```typescript
+viewer.viewerHelper.enable();  // 显示方向 gizmo
+viewer.viewerHelper.disable(); // 隐藏方向 gizmo
+```
+
+**属性：**
+
+| 属性           | 类型        | 说明                                      |
+| :------------- | :---------- | :---------------------------------------- |
+| `location`     | `object`    | gizmo 在画面中的位置，支持 `top`、`bottom`、`left`、`right` 偏移（像素）。默认右下角。 |
+
+```typescript
+// 调整位置到左下角
+viewer.viewerHelper.location.left = 12;
+viewer.viewerHelper.location.bottom = 12;
+viewer.viewerHelper.location.right = null;
+```
+
 ### `dispose()`
 
 清理查看器，从 DOM 中移除 canvas，移除事件监听，并释放渲染器和环境贴图，以防止内存泄漏。

package/docs/getting-started.md

@@ -67,6 +67,7 @@ pnpm install three camera-controls
     el: app,
     rendererOptions: { forceWebGL: false }, // 优先使用 WebGPU
   });
+  await viewer.init();
 
   // 设置背景颜色
   viewer.scene.background = new Color(0x666666);
@@ -92,8 +93,7 @@ pnpm install three camera-controls
 `u-space` 内置了 `InteractionManager`，可以轻松为 3D 对象添加事件监听。
 
 ```javascript
-// 启用指针移动事件
-viewer.interactionManager.targetObjects = [];
+// 启用指针移动事件（pointerenter / pointerleave 需要此开关）
 viewer.interactionManager.pointerMoveEventsEnabled = true;
 
 // 添加点击事件

package/docs/index.md

@@ -48,3 +48,5 @@ features:
 | [curve-movement](./api-plugins#curve-movement) | 沿样条曲线移动相机或对象 |
 | [tracking-controls](./api-plugins#tracking-controls) | 相机跟随移动目标 |
 | [atmosphere](./api-plugins#atmosphere) | 天空/大气渲染（开发中） |
+| [object-controls](./api-plugins#object-controls) | 交互式移动、旋转、缩放 3D 对象 |
+| [topology-drawer](./api-plugins#topology-drawer) | 在场景任意表面交互式绘制拓扑路径图 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-space",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "type": "module",
   "types": "dist/src/index.d.ts",
   "module": "dist/index.js",
@@ -29,7 +29,7 @@
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",
     "docs:deploy": "pnpm docs:build && vercel --prod",
-    "release": "npm version patch && npm publish --access public"
+    "release": "npm version patch && npm publish --access=public"
   },
   "files": [
     "dist",