u-space 0.0.0-alpha.2 → 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-animations.md

@@ -1,10 +1,10 @@
 # Animations API
 
-`u-space` provides a `Tween` class and a `tweenAnimation` helper for animating arbitrary numeric properties. Both are thin wrappers over [`@tweenjs/tween.js`](https://github.com/tweenjs/tween.js) that integrate automatically with the `Viewer` render loop.
+`u-space` 提供了 `Tween` 类和 `tweenAnimation` 辅助函数，用于对任意数值属性进行动画处理。两者都是对 [`@tweenjs/tween.js`](https://github.com/tweenjs/tween.js) 的轻量封装，并自动与 `Viewer` 渲染循环集成。
 
 ## `tweenAnimation`
 
-The simplest way to animate any object's properties. Returns a `Promise` that resolves when the animation completes.
+对任意对象属性执行动画的最简方式，返回一个在动画完成后 resolve 的 `Promise`。
 
 ```typescript
 import { tweenAnimation } from 'u-space';
@@ -13,17 +13,17 @@ const source = { x: 0, y: 0, z: 0 };
 
 await tweenAnimation(
   viewer,
-  source,             // mutable start state (mutated each frame)
-  { x: 10, y: 5, z: 10 }, // target state
+  source,                      // 可变的起始状态（每帧被修改）
+  { x: 10, y: 5, z: 10 },    // 目标状态
   {
-    duration: 1500,   // ms
+    duration: 1500,            // 毫秒
     delay: 0,
     mode: 'Cubic.InOut',
     repeat: false,
     yoyo: false,
   },
   (current) => {
-    // Called every frame with the interpolated values
+    // 每帧以插值结果调用
     myObject.position.set(current.x, current.y, current.z);
   },
 );
@@ -31,23 +31,23 @@ await tweenAnimation(
 
 ### `AnimationOptions`
 
-| Property   | Type                        | Default         | Description                                                  |
-| :--------- | :-------------------------- | :-------------- | :----------------------------------------------------------- |
-| `duration` | `number`                    | `1000`          | Duration in milliseconds.                                    |
-| `delay`    | `number`                    | `0`             | Start delay in milliseconds.                                 |
-| `mode`     | `AnimationModeType`         | `'Linear.None'` | Easing function.                                             |
-| `repeat`   | `number \| boolean`         | `false`         | Number of extra repeats, or `true` for infinite.             |
-| `yoyo`     | `boolean`                   | `false`         | Reverse on each repeat cycle.                                |
+| 属性       | 类型                        | 默认值          | 说明                                               |
+| :--------- | :-------------------------- | :-------------- | :------------------------------------------------- |
+| `duration` | `number`                    | `1000`          | 动画时长（毫秒）。                                 |
+| `delay`    | `number`                    | `0`             | 开始延迟（毫秒）。                                 |
+| `mode`     | `AnimationModeType`         | `'Linear.None'` | 缓动函数。                                         |
+| `repeat`   | `number \| boolean`         | `false`         | 额外重复次数，或 `true` 表示无限循环。             |
+| `yoyo`     | `boolean`                   | `false`         | 在每个循环周期反向播放。                           |
 
 ### `AnimationModeType`
 
-All standard easing modes are supported:
+支持所有标准缓动模式：
 
 `Linear.None` · `Quadratic.In/Out/InOut` · `Cubic.In/Out/InOut` · `Quartic.In/Out/InOut` · `Quintic.In/Out/InOut` · `Sinusoidal.In/Out/InOut` · `Exponential.In/Out/InOut` · `Circular.In/Out/InOut` · `Elastic.In/Out/InOut` · `Back.In/Out/InOut` · `Bounce.In/Out/InOut`
 
 ## `Tween`
 
-A lower-level class for full control. Extends the base `Tween` from `tween.js` and hooks into the `Viewer` event loop via `addEventListener('afterControlsUpdate', ...)`.
+提供完全控制的底层类。继承自 `tween.js` 的基础 `Tween`，并通过 `addEventListener('afterControlsUpdate', ...)` 挂入 `Viewer` 事件循环。
 
 ```typescript
 import { Tween } from 'u-space';
@@ -61,18 +61,18 @@ const tween = new Tween(viewer, source)
     myMaterial.opacity = s.opacity;
     viewer.render();
   })
-  .onComplete(() => console.log('done'));
+  .onComplete(() => console.log('完成'));
 
 tween.start();
 // tween.stop();
 ```
 
-### Methods
+### 方法
 
-| Method                    | Description                                                         |
-| :------------------------ | :------------------------------------------------------------------ |
-| `easingByMode(mode)`      | Convenience shorthand for `.easing(...)` using `AnimationModeType`. |
-| `start(time?)`            | Starts the tween and registers it with the viewer loop.             |
-| `stop()`                  | Stops the tween and unregisters it from the viewer loop.            |
+| 方法                      | 说明                                                            |
+| :------------------------ | :-------------------------------------------------------------- |
+| `easingByMode(mode)`      | 使用 `AnimationModeType` 设置缓动函数的便捷简写。               |
+| `start(time?)`            | 启动补间并注册到 viewer 循环中。                                |
+| `stop()`                  | 停止补间并从 viewer 循环中注销。                                |
 
-All other methods (`to`, `delay`, `repeat`, `yoyo`, `onUpdate`, `onComplete`, `onStop`, `onStart`) are inherited from the base `tween.js` `Tween` class.
+其他方法（`to`、`delay`、`repeat`、`yoyo`、`onUpdate`、`onComplete`、`onStop`、`onStart`）均继承自 `tween.js` 的基础 `Tween` 类。

package/docs/api-effects.md

@@ -1,50 +1,50 @@
 # Effects API
 
-`u-space` provides two static effect utilities built on the Three.js Shading Language (TSL/WebGPU nodes): `MaterialEffects` for applying highlight states to objects, and `TSLEffects` for generating animated color node patterns.
+`u-space` 提供了两个基于 Three.js 着色语言（TSL/WebGPU 节点）的静态特效工具：`MaterialEffects` 用于为对象应用高亮状态，`TSLEffects` 用于生成动态颜色节点模式。
 
 ## `MaterialEffects`
 
-Static utility that applies TSL-based visual effects directly to an object's materials. Works on any `Object3D` — traverses all child meshes automatically.
+静态工具类，将基于 TSL 的视觉特效直接应用于对象的材质。适用于任何 `Object3D`，会自动遍历所有子网格。
 
 ### `MaterialEffects.highlight(object, options?)`
 
-Applies a color/opacity highlight to all meshes in an object. Uses `userData` and TSL node graphs so multiple objects can share the same node graph instance with per-mesh state.
+为对象中所有网格应用颜色/透明度高亮。使用 `userData` 和 TSL 节点图，多个对象可共享同一节点图实例，各自保持独立状态。
 
 ```typescript
 import { MaterialEffects } from 'u-space';
 
-// Highlight an object red with 50% opacity
+// 以 50% 透明度高亮为红色
 MaterialEffects.highlight(myModel, {
   enabled: true,
   color: 0xff0000,
   opacity: 0.5,
-  overwrite: false, // false = tint (multiply), true = replace color
+  overwrite: false, // false = 叠加（相乘），true = 完全替换颜色
 });
 
-// Disable the highlight
+// 禁用高亮
 MaterialEffects.highlight(myModel, { enabled: false });
 ```
 
 ### `HighlightOptions`
 
-| Property   | Type                  | Default     | Description                                                                          |
-| :--------- | :-------------------- | :---------- | :----------------------------------------------------------------------------------- |
-| `enabled`  | `boolean`             | `true`      | Enables or disables the highlight effect.                                            |
-| `color`    | `ColorRepresentation` | `0xff0000`  | Highlight color.                                                                     |
-| `opacity`  | `number`              | `0.5`       | Material opacity when highlighted.                                                   |
-| `overwrite`| `boolean`             | `false`     | `false` = multiply with original color (tint); `true` = replace color entirely.     |
+| 属性        | 类型                  | 默认值      | 说明                                                                         |
+| :---------- | :-------------------- | :---------- | :--------------------------------------------------------------------------- |
+| `enabled`   | `boolean`             | `true`      | 启用或禁用高亮特效。                                                         |
+| `color`     | `ColorRepresentation` | `0xff0000`  | 高亮颜色。                                                                   |
+| `opacity`   | `number`              | `0.5`       | 高亮时材质的透明度。                                                         |
+| `overwrite` | `boolean`             | `false`     | `false` = 与原始颜色相乘（叠加）；`true` = 完全替换颜色。                    |
 
-> **Note:** `highlight` sets `material.transparent = true` on all affected meshes and injects `colorNode`/`opacityNode`. This is currently non-reversible without manually resetting those nodes.
+> **注意：** `highlight` 会在所有受影响的网格上设置 `material.transparent = true`，并注入 `colorNode`/`opacityNode`。目前不可逆，若需恢复须手动重置这些节点。
 
 ---
 
 ## `TSLEffects`
 
-Static factory that returns TSL color nodes. Assign the result to `material.colorNode` on a `NodeMaterial` to apply animated shader effects. Requires `viewer.frameloop = 'always'` for continuous animation.
+静态工厂类，返回 TSL 颜色节点。将返回值赋给 `NodeMaterial` 的 `material.colorNode` 即可应用动态着色器特效。持续动画需要 `viewer.frameloop = 'always'`。
 
 ### `TSLEffects.flow(parameters?)`
 
-A directional light-sweep effect along the mesh UV X-axis — useful for roads, tubes, and flow lines.
+沿网格 UV X 轴方向的定向光扫效果，适用于道路、管道和流线。
 
 ```typescript
 import { TSLEffects } from 'u-space';
@@ -59,19 +59,19 @@ myTubeMesh.material.colorNode = TSLEffects.flow({
 viewer.frameloop = 'always';
 ```
 
-**Parameters:**
+**参数：**
 
-| Property    | Type                  | Default     | Description                                             |
-| :---------- | :-------------------- | :---------- | :------------------------------------------------------ |
-| `baseColor` | `ColorRepresentation` | `0xffffff`  | Background/base color.                                  |
-| `flowColor` | `ColorRepresentation` | `0x00ff00`  | Sweep highlight color.                                  |
-| `speed`     | `number`              | `1.0`       | Animation speed (higher = faster sweep).                |
-| `scale`     | `number`              | `3.0`       | Spatial frequency of the pattern.                       |
-| `intensity` | `number`              | `4.0`       | Peak sharpness — higher values create a narrower beam.  |
+| 属性        | 类型                  | 默认值      | 说明                                              |
+| :---------- | :-------------------- | :---------- | :------------------------------------------------ |
+| `baseColor` | `ColorRepresentation` | `0xffffff`  | 背景/底色。                                       |
+| `flowColor` | `ColorRepresentation` | `0x00ff00`  | 扫光高亮颜色。                                    |
+| `speed`     | `number`              | `1.0`       | 动画速度（越高扫光越快）。                        |
+| `scale`     | `number`              | `3.0`       | 图案的空间频率。                                  |
+| `intensity` | `number`              | `4.0`       | 峰值锐度，值越高光束越细。                        |
 
 ### `TSLEffects.breathe(parameters?)`
 
-A pulsing glow effect that oscillates between two colors over time — suitable for status indicators and alerts.
+在两种颜色之间随时间振荡的脉冲发光效果，适合状态指示器和警报。
 
 ```typescript
 myMesh.material.colorNode = TSLEffects.breathe({
@@ -82,18 +82,18 @@ myMesh.material.colorNode = TSLEffects.breathe({
 });
 ```
 
-**Parameters:**
+**参数：**
 
-| Property      | Type                  | Default    | Description                                      |
-| :------------ | :-------------------- | :--------- | :----------------------------------------------- |
-| `baseColor`   | `ColorRepresentation` | `0xffffff` | Color at the low/rest state.                     |
-| `breathColor` | `ColorRepresentation` | `0x00ff00` | Color at peak brightness.                        |
-| `speed`       | `number`              | `1.0`      | Oscillation speed.                               |
-| `intensity`   | `number`              | `2.0`      | Controls how sharp the peak is.                  |
+| 属性          | 类型                  | 默认值      | 说明                               |
+| :------------ | :-------------------- | :---------- | :--------------------------------- |
+| `baseColor`   | `ColorRepresentation` | `0xffffff`  | 低/静息状态的颜色。                |
+| `breathColor` | `ColorRepresentation` | `0x00ff00`  | 峰值亮度时的颜色。                 |
+| `speed`       | `number`              | `1.0`       | 振荡速度。                         |
+| `intensity`   | `number`              | `2.0`       | 控制峰值的锐度。                   |
 
 ### `TSLEffects.fluid(parameters?)`
 
-A noise-distorted flow effect — useful for water surfaces, plasma, or organic flowing materials.
+噪声扭曲的流动效果，适用于水面、等离子体或有机流动材质。
 
 ```typescript
 myPlaneMesh.material.colorNode = TSLEffects.fluid({
@@ -106,13 +106,13 @@ myPlaneMesh.material.colorNode = TSLEffects.fluid({
 });
 ```
 
-**Parameters:**
+**参数：**
 
-| Property     | Type                  | Default    | Description                                              |
-| :----------- | :-------------------- | :--------- | :------------------------------------------------------- |
-| `baseColor`  | `ColorRepresentation` | `0xffffff` | Base color.                                              |
-| `flowColor`  | `ColorRepresentation` | `0x0000ff` | Fluid highlight color.                                   |
-| `speed`      | `number`              | `1.0`      | Animation speed.                                         |
-| `scale`      | `number`              | `1.0`      | UV scale for the noise pattern.                          |
-| `intensity`  | `number`              | `1.0`      | Sharpness of the fluid pattern.                          |
-| `distortion` | `number`              | `0.5`      | How much the noise distorts the UV before sampling.      |
+| 属性         | 类型                  | 默认值      | 说明                                          |
+| :----------- | :-------------------- | :---------- | :-------------------------------------------- |
+| `baseColor`  | `ColorRepresentation` | `0xffffff`  | 基础颜色。                                    |
+| `flowColor`  | `ColorRepresentation` | `0x0000ff`  | 流体高亮颜色。                                |
+| `speed`      | `number`              | `1.0`       | 动画速度。                                    |
+| `scale`      | `number`              | `1.0`       | 噪声图案的 UV 缩放比例。                      |
+| `intensity`  | `number`              | `1.0`       | 流体图案的锐度。                              |
+| `distortion` | `number`              | `0.5`       | 采样前噪声对 UV 的扭曲程度。                  |