u-space 0.0.0-alpha.1 → 0.0.0-alpha.2

package/README.md

@@ -2,6 +2,8 @@
 
 The library based on three.js with WebGPURenderer.
 
+**[📖 Documentation](https://u-space-phi.vercel.app)**
+
 ## Install
 
 ```bash

package/docs/api-animations.md

@@ -0,0 +1,78 @@
+# 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.
+
+## `tweenAnimation`
+
+The simplest way to animate any object's properties. Returns a `Promise` that resolves when the animation completes.
+
+```typescript
+import { tweenAnimation } from 'u-space';
+
+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
+  {
+    duration: 1500,   // ms
+    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);
+  },
+);
+```
+
+### `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.                                |
+
+### `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', ...)`.
+
+```typescript
+import { Tween } from 'u-space';
+
+const source = { opacity: 1 };
+
+const tween = new Tween(viewer, source)
+  .to({ opacity: 0 }, 800)
+  .easingByMode('Sinusoidal.Out')
+  .onUpdate((s) => {
+    myMaterial.opacity = s.opacity;
+    viewer.render();
+  })
+  .onComplete(() => console.log('done'));
+
+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.            |
+
+All other methods (`to`, `delay`, `repeat`, `yoyo`, `onUpdate`, `onComplete`, `onStop`, `onStart`) are inherited from the base `tween.js` `Tween` class.

package/docs/api-effects.md

@@ -0,0 +1,118 @@
+# 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.
+
+## `MaterialEffects`
+
+Static utility that applies TSL-based visual effects directly to an object's materials. Works on any `Object3D` — traverses all child meshes automatically.
+
+### `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.
+
+```typescript
+import { MaterialEffects } from 'u-space';
+
+// Highlight an object red with 50% opacity
+MaterialEffects.highlight(myModel, {
+  enabled: true,
+  color: 0xff0000,
+  opacity: 0.5,
+  overwrite: false, // false = tint (multiply), true = replace color
+});
+
+// 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.     |
+
+> **Note:** `highlight` sets `material.transparent = true` on all affected meshes and injects `colorNode`/`opacityNode`. This is currently non-reversible without manually resetting those nodes.
+
+---
+
+## `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.
+
+### `TSLEffects.flow(parameters?)`
+
+A directional light-sweep effect along the mesh UV X-axis — useful for roads, tubes, and flow lines.
+
+```typescript
+import { TSLEffects } from 'u-space';
+
+myTubeMesh.material.colorNode = TSLEffects.flow({
+  baseColor: 0x001133,
+  flowColor: 0x00aaff,
+  speed: 1.5,
+  scale: 4.0,
+  intensity: 6.0,
+});
+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.  |
+
+### `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({
+  baseColor: 0x333333,
+  breathColor: 0x00ff88,
+  speed: 2.0,
+  intensity: 3.0,
+});
+```
+
+**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.                  |
+
+### `TSLEffects.fluid(parameters?)`
+
+A noise-distorted flow effect — useful for water surfaces, plasma, or organic flowing materials.
+
+```typescript
+myPlaneMesh.material.colorNode = TSLEffects.fluid({
+  baseColor: 0x002244,
+  flowColor: 0x0066ff,
+  speed: 0.5,
+  scale: 2.0,
+  intensity: 1.5,
+  distortion: 0.3,
+});
+```
+
+**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.      |

package/docs/api-interactions.md

@@ -46,19 +46,64 @@ myBox.addEventListener('click', (eventData) => {
 
 The following event types can be listened to on interactive objects:
 
-- `click`: Fired when the pointer clicks on an object.
+- `click`: Fired when the pointer clicks on an object (filtered: ignored after long press or large move).
 - `dblclick`: Fired when the object is double-clicked rapidly.
+- `contextmenu`: Fired on right-click (prevents default browser context menu).
 - `pointerdown`: Fired when a pointer button is depressed over an object.
-- `pointerup`: Fired when a pointer button is released, generally following a `pointerdown`.
-- `pointerenter`: Fired when the cursor or pointer enters the boundaries of an object.
-- `pointerleave`: Fired when the cursor or pointer leaves the boundaries of an object.
+- `pointerup`: Fired when a pointer button is released over an object.
+- `pointermove`: Fired while the pointer moves over an object. Requires `pointerMoveEventsEnabled = true`.
+- `pointerenter`: Fired when the cursor enters the boundaries of an object. Requires `pointerMoveEventsEnabled = true`.
+- `pointerleave`: Fired when the cursor leaves the boundaries of an object. Requires `pointerMoveEventsEnabled = true`.
 
 ### Event Propagation
 
-To stop an event from continuing to pass through the intersection hierarchy (e.g., clicking on a model inside a larger bounding box), you can stop its propagation using the event payload:
+Events bubble up the parent chain. To stop an event from continuing, call `stopPropagation()` on the event payload:
 
 ```typescript
 myObject.addEventListener('click', (e) => {
   e.event.stopPropagation();
 });
 ```
+
+## `InteractionEvent`
+
+The event object passed to all listener callbacks under the `event` key.
+
+### Properties
+
+| Property        | Type                                       | Description                                                                         |
+| :-------------- | :----------------------------------------- | :---------------------------------------------------------------------------------- |
+| `type`          | `InteractionEventType`                     | The event type string (e.g., `'click'`).                                            |
+| `target`        | `Object3D`                                 | The original 3D object that triggered the event (first intersection).               |
+| `currentTarget` | `Object3D`                                 | The current object in the bubbling chain.                                           |
+| `intersect`     | `Intersection \| null`                     | Three.js raycaster intersection data: `point`, `face`, `distance`, `uv`, etc.       |
+| `originalEvent` | `PointerEvent \| MouseEvent`               | The original DOM pointer/mouse event.                                               |
+
+### Methods
+
+#### `stopPropagation()`
+
+Stops the event from bubbling further up the parent hierarchy.
+
+## `InteractionManager` API
+
+### Properties
+
+| Property                  | Type                          | Default | Description                                                        |
+| :------------------------ | :---------------------------- | :------ | :----------------------------------------------------------------- |
+| `targetObjects`           | `Object3D[] \| null`          | `null`  | Objects to raycast against. `null` means all scene children.       |
+| `pointerMoveEventsEnabled`| `boolean`                     | `false` | Enables `pointermove`, `pointerenter`, `pointerleave` events.      |
+
+### Methods
+
+#### `setCamera(camera)`
+
+Updates the camera used for raycasting. Called automatically by `viewer.setCamera()`.
+
+#### `dispose()`
+
+Removes all DOM event listeners and cleans up internal state.
+
+```typescript
+viewer.interactionManager.dispose();
+```

package/docs/api-managers.md

@@ -48,7 +48,58 @@ sedans.forEach((vehicle) => {
 });
 ```
 
+#### `getByType(type: string)`
+
+Returns a `Set<Object3D>` of all registered objects whose `object.type` matches `type`.
+
+```typescript
+const models = viewer.objectManager.getByType('Model');
+```
+
+#### `getObjectIds(object: Object3D)`
+
+Returns a `Set<string>` of all IDs registered for a given object.
+
+```typescript
+const ids = viewer.objectManager.getObjectIds(myModel);
+```
+
+### Removing Objects
+
+#### `remove(object: Object3D)`
+
+Removes an object and all its associated IDs from all internal maps.
+
+```typescript
+viewer.objectManager.remove(myModel);
+```
+
+#### `removeById(id: string)`
+
+Removes the object registered under the given ID.
+
+```typescript
+viewer.objectManager.removeById('my-unique-car-id');
+```
+
+#### `removeByName(name: string)`
+
+Removes all objects with the given `.name`.
+
+```typescript
+viewer.objectManager.removeByName('sedan');
+```
+
+#### `removeByType(type: string)`
+
+Removes all objects with the given `.type`.
+
+```typescript
+viewer.objectManager.removeByType('Model');
+```
+
 ### Utility Methods
 
-- `getAll()`: Returns all tracked objects.
-- `size`: Returns the total number of objects currently tracked by the manager.
+- `getAll()`: Returns a `Set<Object3D>` of all tracked objects.
+- `clear()`: Removes all objects from all internal maps.
+- `size`: Returns the total number of unique objects currently tracked by the manager.

package/docs/api-objects.md

@@ -2,6 +2,28 @@
 
 `u-space` provides several object wrappers that make manipulating and loading 3D assets easier, primarily extending Three.js's basic nodes.
 
+## Base Classes
+
+### `BaseMesh`
+
+Extends `THREE.Mesh`. All primitive mesh classes in `u-space` inherit from this.
+
+**Key property:**
+
+| Property                     | Type      | Default | Description                                                                     |
+| :--------------------------- | :-------- | :------ | :------------------------------------------------------------------------------ |
+| `ignoreInvisibleWhenRaycast` | `boolean` | `true`  | When `true`, invisible meshes are skipped during raycasting (no hit detection). |
+
+### `BaseGroup`
+
+Extends `THREE.Group`. `Model` and `Topology` inherit from this.
+
+**Key property:**
+
+| Property                     | Type      | Default | Description                                                                      |
+| :--------------------------- | :-------- | :------ | :------------------------------------------------------------------------------- |
+| `ignoreInvisibleWhenRaycast` | `boolean` | `true`  | When `true`, invisible groups are skipped during raycasting (no hit detection).  |
+
 ## Models
 
 The `Model` class extends `BaseGroup` (which in turn extends `THREE.Group`) and simplifies the process of asynchronously loading external 3D models like `glb` and `gltf` files. It features built-in support for different caching layers.
@@ -53,13 +75,237 @@ You can manually clear the internal caches using static methods on the `Model` c
 
 ## Meshes
 
-`u-space` offers a variety of streamlined Mesh classes extending `BaseMesh`. These can be used to quickly construct common 3D shapes without needing to supply geometries or materials right away. They also include built-in interaction event dispatching.
+`u-space` offers a variety of streamlined Mesh classes extending `BaseMesh`. All use `MeshStandardNodeMaterial` by default, accept a `{ geometryParameters, materialParameters }` constructor shape, and support interaction event dispatching.
+
+### `SphereMesh`
+
+```typescript
+import { SphereMesh } from 'u-space';
+
+const sphere = new SphereMesh({
+  geometryParameters: { radius: 1, widthSegments: 32, heightSegments: 32 },
+  materialParameters: { color: 0x0077ff },
+});
+```
+
+**`SphereMeshParameters`**
+
+| Property              | Type                                | Description                              |
+| :-------------------- | :---------------------------------- | :--------------------------------------- |
+| `geometryParameters`  | `SphereGeometry` constructor params | `radius`, `widthSegments`, `heightSegments`, etc. |
+| `materialParameters`  | `MeshStandardNodeMaterialParameters`| Standard material options (color, etc.). |
+
+### `PlaneMesh`
+
+A flat horizontal plane.
+
+```typescript
+import { PlaneMesh } from 'u-space';
+
+const plane = new PlaneMesh({
+  geometryParameters: { width: 10, height: 10 },
+  materialParameters: { color: 0x888888 },
+});
+```
+
+### `CircleMesh`
+
+A flat circle.
+
+```typescript
+import { CircleMesh } from 'u-space';
+
+const circle = new CircleMesh({
+  geometryParameters: { radius: 5, segments: 64 },
+});
+```
+
+### `TubeMesh`
+
+A tube along a given `Curve<Vector3>`.
+
+```typescript
+import { TubeMesh } from 'u-space';
+import { CatmullRomCurve3, Vector3 } from 'three/webgpu';
+
+const path = new CatmullRomCurve3([new Vector3(0,0,0), new Vector3(5,2,5)]);
+const tube = new TubeMesh({
+  geometryParameters: { path, tubularSegments: 20, radius: 0.2, radialSegments: 8 },
+  materialParameters: { color: 0x00ff00 },
+});
+```
+
+### `ShapeMesh`
+
+A flat mesh built from a `THREE.Shape` or from 2D points.
+
+```typescript
+import { ShapeMesh } from 'u-space';
+
+// From an explicit shape
+const mesh = new ShapeMesh({ geometryParameters: { shape: myShape } });
+
+// Static helper: from x/z point array
+const mesh2 = ShapeMesh.createFromPoints([{ x: 0, z: 0 }, { x: 5, z: 0 }, { x: 5, z: 5 }]);
+```
+
+### `ExtrudeMesh`
+
+An extruded 3D solid from a `THREE.Shape` or from 2D points.
+
+```typescript
+import { ExtrudeMesh } from 'u-space';
+
+const solid = new ExtrudeMesh({
+  geometryParameters: {
+    shape: myShape,
+    options: { depth: 3, bevelEnabled: false },
+  },
+  materialParameters: { color: 0xff8800 },
+});
+
+// Static helper
+const solid2 = ExtrudeMesh.createFromPoints(
+  [{ x: 0, z: 0 }, { x: 5, z: 0 }, { x: 5, z: 5 }],
+  { geometryParameters: { options: { depth: 2, bevelEnabled: false } } }
+);
+```
+
+## Poi
+
+`Poi` is a canvas-rendered billboard (sprite) used for placing icons and labels in the 3D scene. It extends `BaseSprite`.
+
+```typescript
+import { Poi } from 'u-space';
+
+const poi = new Poi({
+  img: '/icons/marker.png',
+  text: 'My Location',
+  fontSize: 28,
+  color: '#ffffff',
+  backgroundColor: 'rgba(0,0,0,0.6)',
+  textPosition: 'right',
+});
+await poi.updateAsync(); // render the canvas texture
+
+poi.position.set(10, 5, 10);
+viewer.scene.add(poi);
+```
+
+### `PoiParameters`
+
+| Property          | Type                                        | Default                  | Description                                       |
+| :---------------- | :------------------------------------------ | :----------------------- | :------------------------------------------------ |
+| `img`             | `string \| CanvasImageSource`               | `''`                     | Icon image URL or element.                        |
+| `text`            | `string`                                    | `''`                     | Label text.                                       |
+| `fontSize`        | `number`                                    | `32`                     | Font size in pixels.                              |
+| `fontFamily`      | `string`                                    | `'Arial'`                | Font family.                                      |
+| `color`           | `string`                                    | `'#ffffff'`              | Text color.                                       |
+| `iconSize`        | `number`                                    | `64`                     | Icon size in pixels.                              |
+| `padding`         | `number`                                    | `10`                     | Padding around content.                           |
+| `backgroundColor` | `string`                                    | `'rgba(0, 0, 0, 0.5)'`  | Background fill color.                            |
+| `borderRadius`    | `number`                                    | `8`                      | Background border radius.                         |
+| `textPosition`    | `'top' \| 'bottom' \| 'left' \| 'right'`   | `'right'`                | Text position relative to the icon.               |
+
+### Methods
+
+#### `updateAsync(parameters?)`
+
+Re-renders the canvas texture with optional parameter overrides.
+
+```typescript
+await poi.updateAsync({ text: 'Updated label', color: '#ffff00' });
+viewer.render();
+```
+
+#### `dispose()`
+
+Disposes the canvas texture and material.
+
+## Topology
+
+`Topology` is a graph data structure with built-in 3D visualization. It stores nodes (positions) and weighted edges, implements Dijkstra's shortest-path algorithm, and renders the graph as spheres and tubes.
+
+```typescript
+import { Topology } from 'u-space';
+
+const topo = new Topology({
+  nodeColor: 0x0000ff,
+  nodeRadius: 0.3,
+  edgeColor: 0x00ff00,
+  edgeRadius: 0.05,
+});
+
+topo.addNode('A', new Vector3(0, 0, 0));
+topo.addNode('B', new Vector3(5, 0, 0));
+topo.addNode('C', new Vector3(5, 0, 5));
+
+topo.addEdge('A', 'B');
+topo.addEdge('B', 'C');
+
+topo.renderGraph(); // Creates sphere + tube meshes
+viewer.scene.add(topo);
+```
+
+### `TopologyParameters`
+
+| Property      | Type                 | Default     | Description                     |
+| :------------ | :------------------- | :---------- | :------------------------------ |
+| `nodeColor`   | `ColorRepresentation`| `0x0000ff`  | Color of node spheres.          |
+| `nodeRadius`  | `number`             | `0.5`       | Radius of node spheres.         |
+| `edgeColor`   | `ColorRepresentation`| `0x00ff00`  | Color of edge tubes.            |
+| `edgeRadius`  | `number`             | `0.1`       | Radius of edge tubes.           |
+| `pathColor`   | `ColorRepresentation`| `0xff00ff`  | Color used for path visualization. |
+| `pathRadius`  | `number`             | `0.2`       | Radius of path tubes.           |
+
+### Methods
+
+#### `addNode(id, position)`
+
+Adds a node to the graph.
+
+#### `removeNode(id)`
+
+Removes a node and its associated edges.
+
+#### `addEdge(from, to, weight?, bidirectional?)`
+
+Adds an edge between two nodes. `weight` defaults to Euclidean distance. `bidirectional` defaults to `true`.
+
+#### `removeEdge(from, to, bidirectional?)`
+
+Removes an edge between two nodes.
+
+#### `getShortestPath(startId, endId): Vector3[]`
+
+Returns the shortest path as an array of world-space positions using Dijkstra's algorithm. Returns `[]` if no path exists.
+
+#### `renderGraph()`
+
+Builds the sphere/tube scene graph from current nodes and edges. Call this after modifying the graph to refresh the visualization.
+
+#### `clearGraph()`
+
+Removes and disposes all graph meshes.
+
+#### `renderPath(points, color?): TubeMesh`
+
+Renders a smoothed path (CatmullRomCurve3) through the given points as a tube mesh.
+
+```typescript
+const path = topo.getShortestPath('A', 'C');
+topo.renderPath(path, 0xff0000);
+viewer.render();
+```
+
+#### `clearPaths()`
+
+Removes and disposes all path meshes.
+
+#### `getNeighbors(id): Map<string, number> | undefined`
+
+Returns the adjacency map for a node (neighbor ID → edge weight).
 
-- `CircleMesh`
-- `ExtrudeMesh`
-- `PlaneMesh`
-- `ShapeMesh`
-- `SphereMesh`
-- `TubeMesh`
+#### `dispose()`
 
-These are often initialized directly depending on their specific properties (usually extending `THREE.Mesh` parameters and geometries).
+Clears graph and path meshes.

package/docs/api-plugins.md

@@ -14,90 +14,295 @@ import { KeyboardControls, ACTION } from 'u-space/plugins/keyboard-controls';
 const keyboardControls = new KeyboardControls(viewer);
 
 // Optional: Customize movement speeds
-// keyboardControls.moveDistanceDelta = 2;
-// keyboardControls.rotateAngleDelta = (Math.PI / 180) * 2;
+keyboardControls.moveDistanceDelta = 0.5;
+keyboardControls.rotateAngleDelta = (Math.PI / 180) * 2;
 
 // Activate the listeners
 keyboardControls.enable();
+// Later:
+keyboardControls.disable();
+```
+
+**Default key bindings** (`keyboardControls.keys`):
+
+| Key        | Action            |
+| :--------- | :---------------- |
+| `W`        | Move forward      |
+| `S`        | Move backward     |
+| `A`        | Move left         |
+| `D`        | Move right        |
+| `Q`        | Move up           |
+| `E`        | Move down         |
+| `ArrowLeft`  | Rotate left     |
+| `ArrowRight` | Rotate right    |
+| `ArrowUp`    | Rotate up       |
+| `ArrowDown`  | Rotate down     |
+
+Rebind any key by overwriting the `keys` map with an `ACTION` constant:
+
+```typescript
+import { ACTION } from 'u-space/plugins/keyboard-controls';
+keyboardControls.keys['Space'] = ACTION.MOVE_UP;
 ```
 
 ### `minimap`
 
-Generates a customizable 2D minimap tracking a specific target object within the 3D scene.
+Generates a 2D minimap overlay that tracks a target object within the 3D scene. Renders into an `<canvas>` element injected into `viewer.el`.
 
 ```typescript
 import { Minimap } from 'u-space/plugins/minimap';
 
 const minimap = new Minimap(viewer);
-minimap.target = myCharacterModel;
-minimap.setSize(600, 200);
+minimap.target = myCharacterModel; // Object3D to track and display
+minimap.setSize(300, 300);         // Width and height in pixels
 
-// Style the underlying minimap scene
-minimap.scene.background = new THREE.Color(0xffffff);
+// Optionally style the minimap scene
+minimap.scene.background = new THREE.Color(0x111111);
 
 minimap.enable();
+// Later:
+minimap.disable();
+minimap.dispose();
 ```
 
+**Properties:**
+
+| Property      | Type                  | Description                                          |
+| :------------ | :-------------------- | :--------------------------------------------------- |
+| `target`      | `Object3D \| null`    | The object to center the minimap on.                 |
+| `scene`       | `Scene`               | The minimap's internal Three.js scene.               |
+| `camera`      | `OrthographicCamera`  | The orthographic top-down camera.                    |
+| `marker`      | `Object3D`            | Arrow mesh showing the main camera position/heading. |
+| `needsUpdate` | `boolean`             | Set to `true` to force a minimap re-render.          |
+
+**Methods:**
+
+- `setSize(width, height)` — Resize the minimap canvas and camera frustum.
+- `enable()` — Appends the canvas to `viewer.el` and starts rendering.
+- `disable()` — Removes the canvas and stops rendering.
+- `dispose()` — Disables and cleans up all resources.
+
 ### `tiles`
 
-Provides integration with `3d-tiles-renderer` and geospatial data (like ArcGIS).
+Provides integration with `3d-tiles-renderer` and geospatial data. The main export is `ArcgisTilesRenderer`, which streams ArcGIS Online 3D tiles and re-orients the globe to a specific geographic location.
 
 ```typescript
 import { ArcgisTilesRenderer } from 'u-space/plugins/tiles';
 
 const arcgisTilesRenderer = new ArcgisTilesRenderer(viewer);
 
-// Pass longitude, latitude, and zoom level
+// Set origin to longitude, latitude, altitude
 arcgisTilesRenderer.invalidate(120.002269, 30.284849, 4);
+
+// Tiles stream continuously — use always mode
+viewer.frameloop = 'always';
+
 arcgisTilesRenderer.enable();
 ```
 
+**Methods:**
+
+| Method                         | Description                                                                         |
+| :----------------------------- | :---------------------------------------------------------------------------------- |
+| `invalidate(lon, lat, alt)`    | Sets the tile origin to the given WGS84 coordinates (degrees). Can be called multiple times. Returns an unsubscribe function. |
+| `enable()`                     | Adds tiles to the scene and starts the update loop.                                 |
+| `disable()`                    | Removes tiles from the scene and pauses the update loop.                            |
+| `dispose()`                    | Disables and fully disposes the tile renderer.                                      |
+
 ### `u-manager`
 
-`u-manager` is a comprehensive suite of tools for loading, parsing, and managing complex scene scenarios, properties, visons (camera viewpoints), and animations.
+`u-manager` is a comprehensive suite of loaders and parsers for streaming, decrypting, and displaying structured scene data from a server path. Supports scenes, topologies, animations, properties, and camera viewpoints.
 
-#### Loaders
+All loaders extend Three.js `Loader` and expose a `setPath(path)` method to configure the base data directory before calling `loadAsync()`.
 
-`u-manager` provides loaders to stream various structured data from a defined base path.
+#### `SceneLoader`
 
-```typescript
-import { SceneLoader, TopologiesLoader } from 'u-space/plugins/u-manager';
+Loads the full scene tree (models, groups, shapes, extruded areas) from a server-side scene package. Automatically registers all loaded objects into `viewer.objectManager` by `id` and `sid`.
 
-// Topology loader for multiple models
-const topologiesLoader = new TopologiesLoader();
-topologiesLoader.setPath('./scenes/my-scene');
-const topologies = await topologiesLoader.loadAsync();
-viewer.scene.add(...topologies);
+```typescript
+import { SceneLoader } from 'u-space/plugins/u-manager';
 
-// Comprehensive Scene loader
 const sceneLoader = new SceneLoader(viewer);
 sceneLoader.setPath('./scenes/my-scene');
+sceneLoader.setKey('YOUR_LICENSE_KEY'); // required for OFFICIAL authority scenes
 const group = await sceneLoader.loadAsync();
 viewer.scene.add(group);
 ```
 
-#### Parsers
+**Methods:**
+
+| Method             | Description                                                             |
+| :----------------- | :---------------------------------------------------------------------- |
+| `setKey(key)`      | Sets the RSA decryption key for licensed scenes.                        |
+| `loadAsync()`      | Loads and parses the scene. Returns a `Group` with the full hierarchy.  |
+| `clearCache()`     | Removes all IDs registered by this loader from `objectManager`.         |
+| `dispose()`        | Clears cache and disposes the watermark overlay.                        |
 
-Parsers take the data retrieved by Loaders and execute specific logic in the viewport.
+#### `TopologiesLoader` / `TopologyParser`
+
+Loads topology graph data and converts it into `Topology` objects.
+
+```typescript
+import { TopologiesLoader } from 'u-space/plugins/u-manager';
+
+const loader = new TopologiesLoader();
+loader.setPath('./scenes/my-scene');
+const topologies = await loader.loadAsync(); // Topology[]
+viewer.scene.add(...topologies);
+```
+
+#### `VisionsLoader` / `VisionsParser`
+
+Loads named camera viewpoints and flies the camera to them.
 
 ```typescript
 import { VisionsLoader, VisionsParser } from 'u-space/plugins/u-manager';
 
-// Load viewpoints
-const visionsLoader = new VisionsLoader(viewer);
+const visionsLoader = new VisionsLoader();
 visionsLoader.setPath('./scenes/my-scene');
-const visions = await visionsLoader.loadAsync();
+const visionsData = await visionsLoader.loadAsync();
+// visionsData is a Record<string, IVisions[]>
 
-// Parse and execute camera movement
 const visionsParser = new VisionsParser(viewer);
-// Assuming the loader returned an array of states for key 'HOME'
-await visionsParser.flyTo(visions['HOME'][0]);
+
+// Fly to a specific viewpoint
+await visionsParser.flyTo(visionsData['HOME'][0]);
+
+// Fly to the primary (default) viewpoint
+await visionsParser.flyToPrimary(visionsData['HOME']);
 ```
 
-### Other Plugins
+**`IVisions` fields:**
+
+| Field      | Type          | Description                                |
+| :--------- | :------------ | :----------------------------------------- |
+| `camera`   | `'P' \| 'O'` | Camera type: perspective or orthographic.  |
+| `position` | `IVector3`    | Camera world position.                     |
+| `target`   | `IVector3`    | Camera look-at target.                     |
+| `zoom`     | `number`      | Camera zoom level.                         |
+| `primary`  | `boolean`     | Whether this is the default viewpoint.     |
+
+#### `AnimationsLoader` / `AnimationsParser`
+
+Loads keyframe animation data and drives `Object3D` transforms via `tweenAnimation`.
+
+```typescript
+import { AnimationsLoader, AnimationsParser } from 'u-space/plugins/u-manager';
+
+const animLoader = new AnimationsLoader();
+animLoader.setPath('./scenes/my-scene');
+const animationsData = await animLoader.loadAsync(); // IAnimations[]
+
+// Find the animation for a specific object
+const data = animationsData.find((a) => a.modelId === myModel.userData.id);
 
-The plugins directory also includes:
+const parser = new AnimationsParser(viewer, myModel);
+parser.initTransform(); // save initial position/rotation/scale
 
-- `atmosphere`: For sky rendering.
-- `curve-movement`: For animating objects along predefined paths or splines.
-- `tracking-controls`: Specialized controls for observing moving targets.
+await parser.play(data.keyframes); // plays the sequence
+
+// Stop mid-way
+parser.stop();
+
+// Reset to initial transform
+parser.reset();
+```
+
+#### `PropertiesLoader`
+
+Loads structured property metadata associated with models (e.g., BIM attributes).
+
+```typescript
+import { PropertiesLoader } from 'u-space/plugins/u-manager';
+
+const propsLoader = new PropertiesLoader();
+propsLoader.setPath('./scenes/my-scene');
+const properties = await propsLoader.loadAsync(); // IProperties[]
+
+// Look up properties for a model
+const modelProps = properties.filter(p => p.modelId === myModel.userData.id);
+```
+
+**`IProperties` fields:**
+
+| Field     | Type            | Description                       |
+| :-------- | :-------------- | :-------------------------------- |
+| `modelId` | `string`        | ID of the associated model.       |
+| `group`   | `string`        | Property group/category name.     |
+| `key`     | `string`        | Property key.                     |
+| `value`   | `string \| null`| Property value.                   |
+| `label`   | `string \| null`| Display label for the property.   |
+
+### `curve-movement`
+
+Animates a camera or object along a spline path. Two concrete subclasses are provided: `CurveMovementCamera` and `CurveMovementObject`.
+
+```typescript
+import { CurveMovementObject } from 'u-space/plugins/curve-movement';
+import { Vector3 } from 'three/webgpu';
+
+const movement = new CurveMovementObject(viewer, myModel);
+movement.setFromPoints([
+  new Vector3(0, 0, 0),
+  new Vector3(10, 2, 0),
+  new Vector3(20, 0, 10),
+]);
+movement.speed = 0.05;    // progress per second
+movement.loop = 'repeat'; // 'once' | 'repeat' | 'pingpong'
+movement.autoLookAt = true;
+
+movement.play();
+// movement.pause() / movement.resume() / movement.stop()
+
+// Listen for events
+movement.addEventListener('update', ({ progress }) => console.log(progress));
+movement.addEventListener('complete', () => console.log('done'));
+```
+
+**`CurveMovement` properties:**
+
+| Property        | Type                              | Default   | Description                                  |
+| :-------------- | :-------------------------------- | :-------- | :------------------------------------------- |
+| `path`          | `Curve<Vector3> \| null`          | `null`    | The spline path.                             |
+| `progress`      | `number`                          | `0`       | Current normalized progress (0–1).           |
+| `speed`         | `number`                          | `0.1`     | Progress units per second.                   |
+| `loop`          | `'once' \| 'repeat' \| 'pingpong'`| `'once'`  | Looping behavior.                            |
+| `autoLookAt`    | `boolean`                         | `true`    | Face the path tangent direction.             |
+| `lookAtOffset`  | `number`                          | `0`       | Y-axis rotation offset in radians.           |
+| `positionOffset`| `Vector3`                         | `(0,0,0)` | World-space offset added to each position.   |
+| `direction`     | `1 \| -1`                         | `1`       | Current travel direction.                    |
+
+### `tracking-controls`
+
+Makes the camera smoothly follow a moving `Object3D` target.
+
+```typescript
+import { TrackingControls } from 'u-space/plugins/tracking-controls';
+
+const tracking = new TrackingControls(viewer);
+tracking.target = myMovingObject;
+tracking.type = 'box3';         // 'position' (world origin) or 'box3' (bounding box center)
+tracking.offset.set(0, 5, 0);   // camera target offset
+
+tracking.enable();
+// tracking.disable();
+```
+
+**Properties:**
+
+| Property | Type                    | Default      | Description                                                           |
+| :------- | :---------------------- | :----------- | :-------------------------------------------------------------------- |
+| `target` | `Object3D \| null`      | `null`       | The object to track.                                                  |
+| `type`   | `'position' \| 'box3'` | `'position'` | Whether to track world position or bounding-box center.               |
+| `offset` | `Vector3`               | `(0,0,0)`    | Offset applied to the tracked position before moving the camera.      |
+
+### `atmosphere`
+
+Sky and atmosphere rendering plugin. Currently a placeholder — `enable()` / `disable()` / `dispose()` are available but not yet implemented.
+
+```typescript
+import { Atmosphere } from 'u-space/plugins/atmosphere';
+
+const atmosphere = new Atmosphere(viewer);
+atmosphere.enable();
+```

package/docs/api-viewer.md

@@ -10,10 +10,10 @@ new Viewer(options: ViewerOptions)
 
 ### `ViewerOptions`
 
-| Property          | Type                      | Required | Description                                                                                                           |
-| :---------------- | :------------------------ | :------- | :-------------------------------------------------------------------------------------------------------------------- |
-| `el`              | `HTMLElement`             | Yes      | The DOM element where the WebGPURenderer's canvas will be injected.                                                   |
-| `rendererOptions` | `WebGLRendererParameters` | No       | Options passed directly to the underlying `WebGPURenderer`. By default, it uses high-performance settings for WebGPU. |
+| Property          | Type                       | Required | Description                                                                                                           |
+| :---------------- | :------------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------- |
+| `el`              | `HTMLElement`              | Yes      | The DOM element where the WebGPURenderer's canvas will be injected.                                                   |
+| `rendererOptions` | `WebGPURendererParameters` | No       | Options passed directly to the underlying `WebGPURenderer`. By default, it uses high-performance settings for WebGPU. |
 
 ## Properties
 
@@ -23,12 +23,18 @@ The `Viewer` instance exposes several core Three.js and `u-space` components.
 | :------------------- | :------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------- |
 | `el`                 | `HTMLElement`                               | The container element.                                                                                                  |
 | `renderer`           | `WebGPURenderer`                            | The underlying WebGPU renderer instance.                                                                                |
-| `scene`              | `Scene`                                     | The main Three.js scene.                                                                                                |
+| `scene`              | `Scene`                                     | The main Three.js scene. Background defaults to `0x000000`.                                                             |
 | `camera`             | `PerspectiveCamera` \| `OrthographicCamera` | The active camera.                                                                                                      |
 | `controls`           | `CameraControls`                            | Camera controls (powered by `camera-controls` library).                                                                 |
+| `renderPipeline`     | `RenderPipeline`                            | Manages post-processing passes and the final render call.                                                               |
+| `timer`              | `Timer`                                     | Three.js `Timer` instance for accurate delta time tracking each frame.                                                  |
+| `roomEnvironment`    | `RoomEnvironment`                           | Provides a default room-like IBL environment map for the scene.                                                         |
+| `info`               | `Info`                                      | Renders renderer diagnostics (draw calls, triangles, etc.) as an overlay.                                               |
+| `viewerHelper`       | `ViewerHelper`                              | Exposes utility helpers (e.g., axes, grid display) for development/debugging.                                           |
 | `interactionManager` | `InteractionManager`                        | Manages pointer events and raycasting on objects.                                                                       |
 | `objectManager`      | `ObjectManager`                             | A utility for registering and retrieving objects by ID or name.                                                         |
 | `frameloop`          | `'always'` \| `'demand'`                    | Sets the rendering mode. Default is `'demand'` (render only when required). Set to `'always'` for continuous rendering. |
+| `frameCount`         | `number`                                    | Internal counter of pending render frames. Incremented by `render()`.                                                   |
 
 ## Methods
 
@@ -42,10 +48,13 @@ await viewer.init();
 
 ### `render(frame?: number)`
 
-Requests a render frame. In `'demand'` frameloop mode, this must be called whenever the scene changes visually to update the canvas. `frame` specifies how many frames to render.
+Requests a render frame. In `'demand'` frameloop mode, this must be called whenever the scene changes visually to update the canvas. `frame` specifies how many frames to render (default `1`). Returns a `Promise<void>` that resolves after the frame is rendered.
 
 ```typescript
 viewer.render();
+
+// Await the rendered frame
+await viewer.render();
 ```
 
 ### `setCamera(camera: PerspectiveCamera | OrthographicCamera)`
@@ -65,6 +74,32 @@ Convenience method to switch the camera type while maintaining the viewer contex
 viewer.setCameraByType('orthographic');
 ```
 
+### `createScene()`
+
+Creates and returns a new `Scene` with a black background. Called internally by the constructor but can be used to reset/replace the scene.
+
+```typescript
+viewer.scene = viewer.createScene();
+```
+
+### `createPerspectiveCamera()`
+
+Creates a `PerspectiveCamera` with sensible defaults (50° fov, near `0.1`, far `1e5`, positioned at `(5, 5, 5)`).
+
+```typescript
+const camera = viewer.createPerspectiveCamera();
+viewer.setCamera(camera);
+```
+
+### `createOrthographicCamera()`
+
+Creates an `OrthographicCamera` sized to the container element, near `0.1`, far `1e5`, positioned at `(5, 5, 5)`.
+
+```typescript
+const camera = viewer.createOrthographicCamera();
+viewer.setCamera(camera);
+```
+
 ### `dispose()`
 
 Cleans up the viewer, removing the canvas from the DOM, removing event listeners, and disposing of the renderer and environment maps to prevent memory leaks.

package/docs/getting-started.md

@@ -122,5 +122,10 @@ And that's it! You now have a basic `u-space` application up and running.
 ## Next Steps
 
 - Learn more about the [Viewer API](./api-viewer.md)
-- Explore how to [load Models](./api-objects.md)
+- Explore how to [load Models and work with Objects](./api-objects.md)
 - Understand the [Interaction System](./api-interactions.md)
+- Register and retrieve objects with the [Managers API](./api-managers.md)
+- Add tile maps, minimap, keyboard controls and more with the [Plugins API](./api-plugins.md)
+- Animate properties with the [Animations API](./api-animations.md)
+- Apply visual effects with the [Effects API](./api-effects.md)
+- Browse the [Examples Guide](./examples-guide.md)

package/docs/index.md

@@ -0,0 +1,50 @@
+---
+layout: home
+
+hero:
+  name: u-space
+  text: WebGPU-ready 3D Engine
+  tagline: 基于 Three.js 的插件化 3D 可视化库，支持 GIS 瓦片、动画、场景管理与交互系统。
+  actions:
+    - theme: brand
+      text: 快速上手
+      link: /getting-started
+    - theme: alt
+      text: API 文档
+      link: /api-viewer
+
+features:
+  - title: WebGPU 优先
+    details: 基于 Three.js WebGPU 渲染器，支持 TSL（Three Shading Language）着色器节点，同时保持 WebGL 兼容回退。
+  - title: 插件化架构
+    details: 核心轻量，通过独立插件按需扩展：GIS 瓦片、小地图、键盘控制、场景管理、曲线动画等。
+  - title: 交互系统
+    details: 内置射线检测与事件冒泡，像操作 DOM 元素一样为 3D 对象添加 click、pointerenter 等事件。
+---
+
+## 文档目录
+
+### 核心 API
+
+| 文档 | 说明 |
+| :--- | :--- |
+| [Viewer](./api-viewer) | 核心类：渲染器、场景、相机、控制器、事件 |
+| [Objects](./api-objects) | 3D 对象：模型加载、基础网格、Poi、Topology |
+| [Interactions](./api-interactions) | 交互管理：射线检测、鼠标/触摸事件 |
+| [Managers](./api-managers) | 对象管理：按 ID / 名称 / 类型检索 |
+| [Animations](./api-animations) | 补间动画：`tweenAnimation`、`Tween`、缓动模式 |
+| [Effects](./api-effects) | 视觉特效：高亮、流动、呼吸、流体（TSL） |
+
+### 插件
+
+所有插件从 `u-space/plugins/<name>` 导入。
+
+| 插件 | 说明 |
+| :--- | :--- |
+| [keyboard-controls](./api-plugins#keyboard-controls) | WASD / 方向键控制相机移动与旋转 |
+| [minimap](./api-plugins#minimap) | 2D 小地图叠加层 |
+| [tiles](./api-plugins#tiles) | ArcGIS 3D 瓦片 / GIS 地球渲染 |
+| [u-manager](./api-plugins#u-manager) | 场景加载、拓扑、动画、属性、视点管理 |
+| [curve-movement](./api-plugins#curve-movement) | 沿样条曲线移动相机或对象 |
+| [tracking-controls](./api-plugins#tracking-controls) | 相机跟随移动目标 |
+| [atmosphere](./api-plugins#atmosphere) | 天空/大气渲染（开发中） |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-space",
-  "version": "0.0.0-alpha.1",
+  "version": "0.0.0-alpha.2",
   "type": "module",
   "types": "dist/src/index.d.ts",
   "module": "dist/index.js",
@@ -20,12 +20,23 @@
       ]
     }
   },
+  "scripts": {
+    "build:dev": "vite build --mode development && tsc",
+    "build:u-space": "cross-env BUILD_TARGET=u-space vite build --mode development",
+    "build:plugins": "cross-env BUILD_TARGET=plugins vite build --mode development",
+    "build": "cross-env BUILD_TARGET=all vite build --mode production && tsc",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "docs:deploy": "pnpm docs:build && vercel --prod"
+  },
   "files": [
     "dist",
     "package.json",
     "README.md",
-    "docs"
+    "docs/*.md"
   ],
+  "homepage": "https://u-space-phi.vercel.app",
   "keywords": [
     "u-space",
     "space",
@@ -42,7 +53,8 @@
     "node-rsa": "^1.1.1",
     "typescript": "~5.9.3",
     "vite": "^7.3.1",
-    "vite-plugin-node-polyfills": "^0.24.0"
+    "vite-plugin-node-polyfills": "^0.24.0",
+    "vitepress": "^1.6.4"
   },
   "peerDependencies": {
     "3d-tiles-renderer": "^0.4.19",
@@ -50,11 +62,5 @@
     "@types/three": "^0.183.1",
     "camera-controls": "^3.1.2",
     "three": "^0.183.1"
-  },
-  "scripts": {
-    "build:dev": "vite build --mode development && tsc",
-    "build:u-space": "cross-env BUILD_TARGET=u-space vite build --mode development",
-    "build:plugins": "cross-env BUILD_TARGET=plugins vite build --mode development",
-    "build": "cross-env BUILD_TARGET=all vite build --mode production && tsc"
   }
 }