u-space 0.0.0-alpha.1

package/docs/api-viewer.md

@@ -0,0 +1,84 @@
+# Viewer API
+
+The `Viewer` is the core class of `u-space`. It encapsulates the WebGPU Renderer, Scene, Camera, Controls, and various managers into an easy-to-use interface.
+
+## Constructor
+
+```typescript
+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. |
+
+## Properties
+
+The `Viewer` instance exposes several core Three.js and `u-space` components.
+
+| Property             | Type                                        | Description                                                                                                             |
+| :------------------- | :------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------- |
+| `el`                 | `HTMLElement`                               | The container element.                                                                                                  |
+| `renderer`           | `WebGPURenderer`                            | The underlying WebGPU renderer instance.                                                                                |
+| `scene`              | `Scene`                                     | The main Three.js scene.                                                                                                |
+| `camera`             | `PerspectiveCamera` \| `OrthographicCamera` | The active camera.                                                                                                      |
+| `controls`           | `CameraControls`                            | Camera controls (powered by `camera-controls` library).                                                                 |
+| `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. |
+
+## Methods
+
+### `init()`
+
+Initializes the renderer asynchronously. This must be called if you need to ensure the renderer (like setting up environments or plugins) is fully ready.
+
+```typescript
+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.
+
+```typescript
+viewer.render();
+```
+
+### `setCamera(camera: PerspectiveCamera | OrthographicCamera)`
+
+Sets a custom camera for the viewer and automatically updates the controls and interaction manager to use it.
+
+```typescript
+const customCamera = new PerspectiveCamera(75, width / height, 0.1, 1000);
+viewer.setCamera(customCamera);
+```
+
+### `setCameraByType(type: 'perspective' | 'orthographic')`
+
+Convenience method to switch the camera type while maintaining the viewer context.
+
+```typescript
+viewer.setCameraByType('orthographic');
+```
+
+### `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.
+
+```typescript
+viewer.dispose();
+```
+
+## Events
+
+The viewer extends `EventDispatcher` and fires the following events:
+
+- `beforeControlsUpdate`: Fired before `CameraControls` update. Emitter provides `{ time: number }`.
+- `afterControlsUpdate`: Fired after `CameraControls` update. Emitter provides `{ time: number }`.
+- `beforeRender`: Fired immediately before `renderer.render` is called. Emitter provides `{ time: number }`.
+- `afterRender`: Fired immediately after `renderer.render` completes. Emitter provides `{ time: number }`.
+- `cameraChange`: Fired when `setCamera` is called. Emitter provides `{ camera: Camera }`.

package/docs/examples-guide.md

@@ -0,0 +1,48 @@
+# Examples Guide
+
+`u-space` contains an extensive `examples/` directory that demonstrates the engine's capabilities. Below are a few key examples and what they teach you about the system.
+
+## 1. `demo01.html`: Basic Setup & Interactivity
+
+This example demonstrates the absolute bare-minimum setup required to get a 3D scene rendering via WebGPU, as covered in the [Getting Started](./getting-started.md) guide.
+
+### Key Takeaways:
+
+- Injecting the `Viewer` into a DOM element.
+- Setting the scene background using WebGPU `Color`.
+- Adding primitive geometries (like `BoxGeometry`).
+- Enabling global interaction via `viewer.interactionManager.pointerMoveEventsEnabled`.
+- Attaching DOM-style event listeners (`click`, `pointerenter`, `pointerleave`) natively to 3D meshes.
+
+## 2. `test_loader.html`: Model Caching Mechanics
+
+This example dives deep into the `u-space` Model Loader pipeline and explains the differences between runtime cache and browser persistent cache.
+
+### Key Takeaways:
+
+- Utilizing the global `Model` class to load `.glb` files asynchronously via `Model.prototype.loadAsync()`.
+- Demystifying `cache: true` (which retains the model node in RAM for instant cloning/instantiation).
+- Demystifying `persistent: true` (which uses the Service Worker / Cache Storage API to cache the actual network request bytes).
+- Demonstrates how to register these loaded asynchronous assets into the `viewer.objectManager` securely.
+- Provides examples on programmatically flushing the caches using `Model.clearMemoryCache()` and `Model.clearPersistentCache()`.
+
+## 3. `load_tiles.html`: GIS & Earth Rendering
+
+This example uses the external `3d-tiles-renderer` peer dependency securely wrapped by a `u-space` plugin to render massive level-of-detail GIS globes.
+
+### Key Takeaways:
+
+- Instantiating complex plugins (`ArcgisTilesRenderer`) dynamically passing the core viewer reference.
+- Using `viewer.frameloop = 'always'` since tiles stream asynchronously and continuously update the viewport.
+- Fetching specific Longitude and Latitude positions using the plugin's `invalidate(lon, lat, zoom)` method.
+
+## 4. `test_umanager.html`: Scene Compositions & Parsers
+
+This robust example combines multiple tools, illustrating how to build complete applications instead of just placing single models.
+
+### Key Takeaways:
+
+- Initializing multiple Plugins concurrently (minimap, tracking, keyboard-controls) and toggling their state via `.enable()` / `.disable()`.
+- Streaming structured scene layouts, parsing scene descriptions (`SceneLoader`, `TopologiesLoader`).
+- Working with camera animations (`VisionsLoader` and `VisionsParser`) to choreograph pre-defined flight paths securely within the scene.
+- Retrieving complex Node materials and customizing WebGPU specific TSL (Three Shading Language) nodes like `TSLEffects.fluid()`.

package/docs/getting-started.md

@@ -0,0 +1,126 @@
+# Getting Started with `u-space`
+
+`u-space` is a WebGPU-ready 3D engine built on top of Three.js. This guide will show you how to set up a basic `u-space` application.
+
+## Installation
+
+Ensure you have `@types/three` and `three` installed as peer dependencies. If you plan to use interactions, you might also need `camera-controls`.
+
+```bash
+pnpm install three camera-controls
+```
+
+## Basic Setup
+
+Here is a minimal example of setting up a `u-space` `Viewer` and adding an interactive object to the scene.
+
+### 1. HTML Structure
+
+Create an element to house your 3D viewer.
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>u-space App</title>
+  </head>
+  <body style="margin: 0">
+    <div id="app" style="width: 100vw; height: 100vh"></div>
+    <!-- Script goes here -->
+  </body>
+</html>
+```
+
+### 2. Import Maps
+
+Since `u-space` relies on Three.js WebGPU features, it's recommended to set up an import map to resolve the WebGPU build of Three.js.
+
+```html
+<script type="importmap">
+  {
+    "imports": {
+      "three": "/node_modules/three/build/three.webgpu.js",
+      "three/webgpu": "/node_modules/three/build/three.webgpu.js",
+      "three/addons/": "/node_modules/three/examples/jsm/",
+      "camera-controls": "/node_modules/camera-controls/dist/camera-controls.module.js",
+      "u-space": "path/to/u-space/dist/index.js"
+    }
+  }
+</script>
+```
+
+### 3. Initialize Viewer & Add Objects
+
+Now, initialize the `Viewer` and add a basic Three.js object to the scene.
+
+```html
+<script type="module">
+  import { Color, GridHelper, Mesh, BoxGeometry, MeshBasicMaterial } from 'three/webgpu';
+  import { Viewer } from 'u-space';
+
+  const app = document.getElementById('app');
+
+  // Initialize the viewer
+  const viewer = new Viewer({
+    el: app,
+    rendererOptions: { forceWebGL: false }, // Prefer WebGPU
+  });
+
+  // Set background color
+  viewer.scene.background = new Color(0x666666);
+
+  // Add a grid
+  const gridHelper = new GridHelper(10, 10);
+  viewer.scene.add(gridHelper);
+
+  // Add a Box
+  const geometry = new BoxGeometry(1, 1, 1);
+  const material = new MeshBasicMaterial({ color: 0xff0000 });
+  const box = new Mesh(geometry, material);
+  box.position.set(0, 0.5, 0);
+  viewer.scene.add(box);
+
+  // Render the scene
+  viewer.render();
+</script>
+```
+
+### 4. Enable Interactions
+
+`u-space` has a built-in `InteractionManager`. You can easily add event listeners to your 3D objects.
+
+```javascript
+// Enable pointer move events
+viewer.interactionManager.targetObjects = [];
+viewer.interactionManager.pointerMoveEventsEnabled = true;
+
+// Add click event
+box.addEventListener('click', (e) => {
+  console.log('Clicked at:', e.event.intersect.point);
+  material.color.set(Math.random() * 0xffffff);
+  viewer.render(); // Request a new frame
+});
+
+// Add hover events
+box.addEventListener('pointerenter', (e) => {
+  document.body.style.cursor = 'pointer';
+  material.color.set(0x00ff00);
+  viewer.render();
+});
+
+box.addEventListener('pointerleave', (e) => {
+  document.body.style.cursor = 'default';
+  material.color.set(0xff0000);
+  viewer.render();
+});
+```
+
+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)
+- Understand the [Interaction System](./api-interactions.md)

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "u-space",
+  "version": "0.0.0-alpha.1",
+  "type": "module",
+  "types": "dist/src/index.d.ts",
+  "module": "dist/index.js",
+  "main": "dist/index.cjs",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./plugins/*": "./dist/plugins/*/index.js"
+  },
+  "typesVersions": {
+    "*": {
+      "plugins/*": [
+        "./dist/plugins/*/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "README.md",
+    "docs"
+  ],
+  "keywords": [
+    "u-space",
+    "space",
+    "3d",
+    "webgpu",
+    "threejs",
+    "three",
+    "camera-controls"
+  ],
+  "devDependencies": {
+    "@types/node-rsa": "^1.1.4",
+    "cross-env": "^10.1.0",
+    "crypto-browserify": "^3.12.1",
+    "node-rsa": "^1.1.1",
+    "typescript": "~5.9.3",
+    "vite": "^7.3.1",
+    "vite-plugin-node-polyfills": "^0.24.0"
+  },
+  "peerDependencies": {
+    "3d-tiles-renderer": "^0.4.19",
+    "@takram/three-geospatial": "^0.6.0",
+    "@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"
+  }
+}