u-space 0.0.1 → 0.0.2

package/dist/plugins/topology-drawer/TopologyDrawer.d.ts

@@ -0,0 +1,97 @@
+import { type ColorRepresentation } from 'three/webgpu';
+import { type Viewer, Topology, type TopologyParameters, type TopologyData } from 'u-space';
+export interface TopologyDrawerOptions extends TopologyParameters {
+    /** Y coordinate of the fallback ground plane (used when no scene object is hit). Default: 0 */
+    groundY?: number;
+    /** Color of the preview line shown while drawing. Default: 0xffff00 */
+    previewColor?: ColorRepresentation;
+    /** Snap to an existing node when clicking within this world-unit radius. Default: 1.0 */
+    snapRadius?: number;
+}
+/**
+ * Interactive plugin for drawing topology graphs on any surface in the scene.
+ *
+ * Detection uses `viewer.interactionManager` — events fired on hit objects bubble
+ * up the parent chain and are caught by `scene.addEventListener`.
+ * An invisible ground plane is added to the scene as a fallback so that clicks
+ * on empty space (no other object hit) still produce a valid world point.
+ *
+ * Controls (while enabled):
+ *   - Left-click           : Place a node on the surface under the cursor
+ *                            (snaps to nearest existing node within snapRadius)
+ *   - Right-click / Escape : Finish the current path chain
+ *   - Ctrl/Cmd + Z         : Undo the last action
+ */
+declare class TopologyDrawer {
+    viewer: Viewer;
+    topology: Topology;
+    private _snapRadius;
+    private _scene;
+    private _groundMesh;
+    private _previewLine;
+    private _previewGeometry;
+    private _lastNodeId;
+    private _nodeCounter;
+    private _history;
+    private _enabled;
+    private _prevFrameloop;
+    private _prevPointerMoveEnabled;
+    constructor(viewer: Viewer, options?: TopologyDrawerOptions);
+    private _findNearestNode;
+    private _setPreviewLine;
+    /**
+     * 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.
+     */
+    private _resolvePoint;
+    private _placePoint;
+    /**
+     * 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.
+     */
+    private _splitEdge;
+    private _onSceneClick;
+    private _onScenePointerMove;
+    private _onSceneContextMenu;
+    private _onKeyDown;
+    /** Finish the current path chain. Next click starts an unconnected new path. */
+    finishPath(): void;
+    /** Undo the last action (node, edge, or finishPath). */
+    undo(): void;
+    /** Remove all drawn nodes, edges, and path meshes. */
+    clear(): void;
+    /** Export the current topology as a JSON-serializable object. Delegates to `topology.exportData()`. */
+    exportData(): TopologyData;
+    /**
+     * Load a previously exported topology, replacing any current drawing.
+     * Delegates to `topology.importData()` and resets the drawer's internal node counter.
+     */
+    importData(data: TopologyData): void;
+    /**
+     * 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(): this;
+    /**
+     * Disable drawing mode.
+     * The drawn topology remains visible in the scene.
+     */
+    disable(): this;
+    /** Fully dispose all resources and remove the topology from the scene. */
+    dispose(): void;
+}
+export { TopologyDrawer };

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

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const d=require("three/webgpu"),r=require("u-space");class h{viewer;topology;_snapRadius;_scene;_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 r.Topology({nodeColor:t?.nodeColor,nodeRadius:t?.nodeRadius,edgeColor:t?.edgeColor,edgeRadius:t?.edgeRadius,pathColor:t?.pathColor,pathRadius:t?.pathRadius});const o=new d.PlaneGeometry(1e5,1e5);o.rotateX(-Math.PI/2),this._groundMesh=new d.Mesh(o,new d.MeshBasicNodeMaterial({visible:!1})),this._groundMesh.position.y=t?.groundY??0,this._previewGeometry=new d.BufferGeometry,this._previewGeometry.setAttribute("position",new d.Float32BufferAttribute(new Float32Array(6),3)),this._previewLine=new d.Line(this._previewGeometry,new d.LineBasicNodeMaterial({color:t?.previewColor??16776960,depthTest:!1})),this._previewLine.renderOrder=10,this._previewLine.visible=!1}_findNearestNode(e){let t=this._snapRadius,o=null;return this.topology.nodes.forEach((i,s)=>{const n=e.distanceTo(i);n<t&&(t=n,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}_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()}_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 n={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),n.chainEdge={from:this._lastNodeId,to:s}),this._history.push(n),this._lastNodeId=s,this.topology.renderGraph()}_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())};finishPath(){this._history.push({type:"finishPath",prevLastNodeId:this._lastNodeId}),this._lastNodeId=null,this._previewLine.visible=!1}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}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}exportData(){return this.topology.exportData()}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(){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(){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}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()}}exports.TopologyDrawer=h;

package/dist/plugins/topology-drawer/index.d.ts

@@ -0,0 +1 @@
+export * from './TopologyDrawer';

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-plugins.md

@@ -306,3 +306,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/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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-space",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "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 publish --access=public"
   },
   "files": [
     "dist",