u-space 0.0.3 → 0.0.7

package/dist/src/effects/MaterialEffects.d.ts

@@ -1,10 +1,17 @@
 import { type Object3D, type ColorRepresentation } from 'three/webgpu';
-export interface HighlightOptions {
-    enabled?: boolean;
+export interface HighlightColorOptions {
     opacity?: number;
     color?: ColorRepresentation;
     overwrite?: boolean;
 }
+export interface BreatheColorOptions {
+    color?: ColorRepresentation;
+    speed?: number;
+    intensity?: number;
+}
 export declare class MaterialEffects {
-    static highlight(object: Object3D, options?: HighlightOptions): void;
+    static highlightColor(object: Object3D | Object3D[], options?: HighlightColorOptions): void;
+    static removeHighlightColor(object: Object3D | Object3D[]): void;
+    static breatheColor(object: Object3D | Object3D[], options?: BreatheColorOptions): void;
+    static removeBreatheColor(object: Object3D | Object3D[]): void;
 }

package/dist/src/index.d.ts

@@ -7,3 +7,11 @@ export * from './effects';
 export * from './animations';
 export * from './interfaces';
 export * from './types';
+export declare const version: string;
+declare global {
+    interface Window {
+        __USPACE__: {
+            version: string;
+        };
+    }
+}

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

@@ -1,4 +1,4 @@
-import { type Object3D } from 'three/webgpu';
+import { type Object3D, AnimationMixer, type AnimationAction, type AnimationClip } from 'three/webgpu';
 import { type InteractionEventMap } from '../interactions';
 import { BaseGroup } from './BaseGroup';
 export interface ModelParameters {
@@ -6,12 +6,25 @@ export interface ModelParameters {
     cache?: boolean;
     persistent?: boolean;
 }
+export interface PlayAnimationOptions {
+    loop?: boolean;
+    repetitions?: number;
+    timeScale?: number;
+    clampWhenFinished?: boolean;
+}
 export declare class Model extends BaseGroup<InteractionEventMap> {
     readonly isModel = true;
     type: string;
     private static memoryCache;
+    mixer: AnimationMixer | null;
+    animations: AnimationClip[];
+    private actions;
     constructor();
     loadAsync(parameters: ModelParameters): Promise<Object3D<import("three").Object3DEventMap> | null>;
+    playAnimation(nameOrIndex?: string | number, options?: PlayAnimationOptions): AnimationAction | null;
+    playAllAnimations(options?: PlayAnimationOptions): AnimationAction[];
+    stopAnimation(nameOrIndex?: string | number): void;
+    updateAnimation(delta: number): void;
     static clearMemoryCache(): void;
     static clearPersistentCache(): Promise<void>;
 }

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

@@ -21,11 +21,15 @@ export interface PoiParameters {
     borderRadius?: number;
     /** Text position relative to the icon */
     textPosition?: 'top' | 'bottom' | 'left' | 'right';
+    /** Scale factor for mapping canvas pixels to world units */
+    scaleFactor?: number;
 }
 export declare class Poi extends BaseSprite<InteractionEventMap> {
     readonly isPoi = true;
     type: string;
     parameters: Required<PoiParameters>;
+    private _canvas;
+    private _lastParametersJSON;
     constructor(parameters?: PoiParameters);
     /**
      * Update the POI with new parameters

package/dist/src/viewers/CSSRenderer.d.ts

@@ -0,0 +1,19 @@
+import { CSS2DRenderer, CSS2DObject } from 'three/addons/renderers/CSS2DRenderer.js';
+import { CSS3DRenderer, CSS3DObject, CSS3DSprite } from 'three/addons/renderers/CSS3DRenderer.js';
+import type { Scene, Camera } from 'three/webgpu';
+export { CSS2DObject, CSS3DObject, CSS3DSprite };
+declare class CSSRenderer {
+    el: HTMLElement;
+    css2dRenderer: CSS2DRenderer | null;
+    css3dRenderer: CSS3DRenderer | null;
+    constructor(el: HTMLElement);
+    private initCSS2DRenderer;
+    private initCSS3DRenderer;
+    createCSS2DObject(element: HTMLElement): CSS2DObject;
+    createCSS25DObject(element: HTMLElement): CSS3DSprite;
+    createCSS3DObject(element: HTMLElement): CSS3DObject;
+    render(scene: Scene, camera: Camera): void;
+    resize(width: number, height: number): void;
+    dispose(): void;
+}
+export { CSSRenderer };

package/dist/src/viewers/CameraControls.d.ts

@@ -1,5 +1,6 @@
 import CameraControlsBase from 'camera-controls';
 import { Box3, type Object3D } from 'three/webgpu';
+import type { IVector3 } from '../interfaces';
 export interface FlyToBoxOptions {
     viewpoint?: 'current' | 'top' | 'bottom' | 'front' | 'back' | 'left' | 'right' | 'frontTop' | 'backTop' | 'leftTop' | 'rightTop' | 'leftFrontTop' | 'rightFrontTop' | 'leftBackTop' | 'rightBackTop';
     enableTransition?: boolean;
@@ -8,6 +9,11 @@ export interface FlyToBoxOptions {
 }
 export interface FlyToObjectOptions extends FlyToBoxOptions {
 }
+export interface CameraViewpointData {
+    position: IVector3;
+    target: IVector3;
+    zoom: number;
+}
 export declare class CameraControls extends CameraControlsBase {
     constructor(...args: ConstructorParameters<typeof CameraControlsBase>);
     /**
@@ -16,4 +22,5 @@ export declare class CameraControls extends CameraControlsBase {
     absoluteRotations(): void;
     flyToBox(box: Box3, options?: FlyToBoxOptions): Promise<boolean>;
     flyToObject(object: Object3D, options?: FlyToObjectOptions): Promise<boolean>;
+    setCameraViewpoint(viewpoint: CameraViewpointData, enableTransition?: boolean): Promise<[void, void]>;
 }

package/dist/src/viewers/RenderPipeline.d.ts

@@ -1,17 +1,45 @@
-import { type Scene, type Camera, RenderPipeline as RenderPipelineBase, type Node } from 'three/webgpu';
+import { type Scene, type Camera, type PassNode, RenderPipeline as RenderPipelineBase, type Node } from 'three/webgpu';
+export interface BloomConfig {
+    strength?: number;
+    radius?: number;
+    threshold?: number;
+}
+export interface SSGIConfig {
+    sliceCount?: number;
+    stepCount?: number;
+    aoIntensity?: number;
+    giIntensity?: number;
+    radius?: number;
+    thickness?: number;
+}
+export type OutputNodeComposer = (scenePass: PassNode) => Node;
 type Args = [ConstructorParameters<typeof RenderPipelineBase>[0], Scene, Camera];
 export declare class RenderPipeline extends RenderPipelineBase {
     #private;
     scene: Scene;
     camera: Camera;
-    currentOutputNode: Node;
+    scenePass: PassNode;
     needsUpdateOutputNode: boolean;
     constructor(...args: Args);
+    /** @deprecated Use `scenePass` instead */
+    get currentOutputNode(): PassNode;
     addOverlayPass(pass: Node): void;
     removeOverlayPass(pass: Node): void;
     setCamera(camera: Camera): void;
+    /** @deprecated Use `setOutputComposer` instead */
     setCurrentOutputNode(node: Node): void;
+    /** @deprecated Use `setOutputComposer(null)` instead */
     resetCurrentOutputNode(): void;
+    setOutputComposer(composer: OutputNodeComposer | null): void;
+    enableBloom(config?: BloomConfig): void;
+    disableBloom(): void;
+    updateBloom(config: Partial<BloomConfig>): void;
+    enableSSGI(config?: SSGIConfig): void;
+    disableSSGI(): void;
+    updateSSGI(config: Partial<SSGIConfig>): void;
+    enableTRAA(): void;
+    disableTRAA(): void;
     render(): void;
+    dispose(): void;
 }
 export {};

package/dist/src/viewers/Viewer.d.ts

@@ -5,6 +5,7 @@ import { RenderPipeline } from './RenderPipeline';
 import { CameraControls } from './CameraControls';
 import { RoomEnvironment } from './RoomEnvironment';
 import { ViewerHelper } from './ViewerHelper';
+import { CSSRenderer } from './CSSRenderer';
 import { Info } from './Info';
 type ViewerRendererOptions = ConstructorParameters<typeof WebGPURenderer>['0'];
 export interface ViewerOptions {
@@ -14,15 +15,19 @@ export interface ViewerOptions {
 export interface ViewerEventMap {
     beforeControlsUpdate: {
         time: number;
+        delta: number;
     };
     afterControlsUpdate: {
         time: number;
+        delta: number;
     };
     beforeRender: {
         time: number;
+        delta: number;
     };
     afterRender: {
         time: number;
+        delta: number;
     };
     cameraChange: {
         camera: PerspectiveCamera | OrthographicCamera;
@@ -41,6 +46,7 @@ declare class Viewer extends EventDispatcher<ViewerEventMap> {
     interactionManager: InteractionManager;
     objectManager: ObjectManager;
     viewerHelper: ViewerHelper;
+    cssRenderer: CSSRenderer;
     frameCount: number;
     frameloop: 'always' | 'demand';
     constructor({ el, rendererOptions }: ViewerOptions);

package/dist/src/viewers/index.d.ts

@@ -1,3 +1,5 @@
 export * from './Viewer';
+export * from './RenderPipeline';
+export * from './CSSRenderer';
 export * from './RoomEnvironment';
 export * from './CameraControls';

package/docs/api-css-renderer.md

@@ -0,0 +1,43 @@
+# CSSRenderer API
+
+`viewer.cssRenderer` 用于在 3D 场景中叠加渲染 HTML 元素。支持三种模式：
+
+| 模式 | 方法 | 返回类型 | 说明 |
+| :--- | :--- | :------- | :--- |
+| CSS2D | `createCSS2DObject(element)` | `CSS2DObject` | HTML 元素始终面向相机，屏幕尺寸固定不随距离缩放。适合标签、工具提示。 |
+| CSS2.5D | `createCSS25DObject(element)` | `CSS3DSprite` | HTML 元素面向相机，但尺寸随距离缩放（近大远小）。 |
+| CSS3D | `createCSS3DObject(element)` | `CSS3DObject` | HTML 元素具有完整的 3D 变换，可旋转、缩放，参与透视投影。适合面板、信息板。 |
+
+底层渲染器采用**懒加载**：首次调用对应 `create` 方法时才初始化 `CSS2DRenderer` 或 `CSS3DRenderer`，不使用则无开销。
+
+创建的对象是标准 Three.js `Object3D`，直接添加到场景中即可：
+
+```typescript
+// CSS2D 标签
+const labelEl = document.createElement('div');
+labelEl.textContent = '标签';
+labelEl.style.cssText = 'background:rgba(0,0,0,0.7);color:#fff;padding:4px 8px;border-radius:4px;font-size:13px;';
+const label = viewer.cssRenderer.createCSS2DObject(labelEl);
+label.position.set(0, 2, 0);
+viewer.scene.add(label);
+
+// CSS2.5D 精灵（需设置 scale，通常 0.01 左右）
+const spriteEl = document.createElement('div');
+spriteEl.textContent = '精灵';
+const sprite = viewer.cssRenderer.createCSS25DObject(spriteEl);
+sprite.position.set(3, 2, 0);
+sprite.scale.setScalar(0.01);
+viewer.scene.add(sprite);
+
+// CSS3D 面板（需设置 scale，通常 0.01 左右）
+const panelEl = document.createElement('div');
+panelEl.innerHTML = '<h3>面板</h3><p>3D 空间中的 HTML</p>';
+const panel = viewer.cssRenderer.createCSS3DObject(panelEl);
+panel.position.set(0, 1.5, -3);
+panel.scale.setScalar(0.01);
+viewer.scene.add(panel);
+```
+
+> `CSSRenderer` 的生命周期（渲染、缩放、销毁）已自动集成到 `Viewer` 中，无需手动调用。
+
+同时从 `u-space` 包中导出了 `CSS2DObject`、`CSS3DObject`、`CSS3DSprite` 类型，供直接使用。

package/docs/api-effects.md

@@ -1,40 +1,78 @@
 # Effects API
 
-`u-space` 提供了两个基于 Three.js 着色语言（TSL/WebGPU 节点）的静态特效工具：`MaterialEffects` 用于为对象应用高亮状态，`TSLEffects` 用于生成动态颜色节点模式。
+`u-space` 提供了两个基于 Three.js 着色语言（TSL/WebGPU 节点）的静态特效工具：`MaterialEffects` 用于为对象应用高亮、呼吸等材质特效，`TSLEffects` 用于生成动态颜色节点模式。
 
 ## `MaterialEffects`
 
-静态工具类，将基于 TSL 的视觉特效直接应用于对象的材质。适用于任何 `Object3D`，会自动遍历所有子网格。
+静态工具类，将基于 TSL 的视觉特效直接应用于对象的材质。适用于任何 `Object3D`（支持单个或数组），会自动遍历所有子网格。
 
-### `MaterialEffects.highlight(object, options?)`
+特性：
+- **效果可叠加**：高亮和呼吸效果可同时作用于同一对象，呼吸在高亮结果之上混合
+- **共享材质安全**：按材质跟踪引用计数，多个 Mesh 共享材质时互不干扰
+- **完整还原**：移除效果时自动恢复材质原始的 `colorNode`、`opacityNode` 和 `transparent` 状态
 
-为对象中所有网格应用颜色/透明度高亮。使用 `userData` 和 TSL 节点图，多个对象可共享同一节点图实例，各自保持独立状态。
+### `MaterialEffects.highlightColor(object, options?)`
+
+为对象中所有网格应用颜色/透明度高亮。
 
 ```typescript
 import { MaterialEffects } from 'u-space';
 
 // 以 50% 透明度高亮为红色
-MaterialEffects.highlight(myModel, {
-  enabled: true,
+MaterialEffects.highlightColor(myModel, {
   color: 0xff0000,
   opacity: 0.5,
   overwrite: false, // false = 叠加（相乘），true = 完全替换颜色
 });
 
-// 禁用高亮
-MaterialEffects.highlight(myModel, { enabled: false });
+// 支持数组
+MaterialEffects.highlightColor([model1, model2], { color: 0x00ff00 });
 ```
 
-### `HighlightOptions`
+#### `HighlightColorOptions`
 
 | 属性        | 类型                  | 默认值      | 说明                                                                         |
 | :---------- | :-------------------- | :---------- | :--------------------------------------------------------------------------- |
-| `enabled`   | `boolean`             | `true`      | 启用或禁用高亮特效。                                                         |
 | `color`     | `ColorRepresentation` | `0xff0000`  | 高亮颜色。                                                                   |
 | `opacity`   | `number`              | `0.5`       | 高亮时材质的透明度。                                                         |
 | `overwrite` | `boolean`             | `false`     | `false` = 与原始颜色相乘（叠加）；`true` = 完全替换颜色。                    |
 
-> **注意：** `highlight` 会在所有受影响的网格上设置 `material.transparent = true`，并注入 `colorNode`/`opacityNode`。目前不可逆，若需恢复须手动重置这些节点。
+### `MaterialEffects.removeHighlightColor(object)`
+
+移除高亮效果。当对象上所有效果都被移除后，材质将完整恢复到原始状态。
+
+```typescript
+MaterialEffects.removeHighlightColor(myModel);
+```
+
+### `MaterialEffects.breatheColor(object, options?)`
+
+为对象应用呼吸灯效果，颜色在材质原色与目标颜色之间随时间脉冲变化。需要 `viewer.frameloop = 'always'`。
+
+```typescript
+MaterialEffects.breatheColor(myModel, {
+  color: 0x00ff00,
+  speed: 1.0,
+  intensity: 2.0,
+});
+viewer.frameloop = 'always';
+```
+
+#### `BreatheColorOptions`
+
+| 属性        | 类型                  | 默认值      | 说明                               |
+| :---------- | :-------------------- | :---------- | :--------------------------------- |
+| `color`     | `ColorRepresentation` | `0x00ff00`  | 呼吸目标颜色。                     |
+| `speed`     | `number`              | `1.0`       | 振荡速度。                         |
+| `intensity` | `number`              | `2.0`       | 控制峰值的锐度。                   |
+
+### `MaterialEffects.removeBreatheColor(object)`
+
+移除呼吸效果。
+
+```typescript
+MaterialEffects.removeBreatheColor(myModel);
+```
 
 ---
 

package/docs/api-objects.md

@@ -66,6 +66,64 @@ const model3 = new Model();
 model3.loadAsync({ url: 'model.glb', cache: true, persistent: true });
 ```
 
+### 动画
+
+`Model` 在加载含内置动画的模型（如 glTF/FBX）后，会自动初始化 `AnimationMixer` 并收集 `AnimationClip`。
+
+**属性：**
+
+| 属性         | 类型                        | 说明                                       |
+| :----------- | :-------------------------- | :----------------------------------------- |
+| `mixer`      | `AnimationMixer \| null`    | 动画混合器，加载含动画模型后自动创建。     |
+| `animations` | `AnimationClip[]`           | 模型内置的动画片段列表。                   |
+
+#### `playAnimation(nameOrIndex?, options?)`
+
+播放指定动画。不传参时播放第一个动画。
+
+```typescript
+// 按名称播放
+model.playAnimation('Walk');
+
+// 按索引播放
+model.playAnimation(0);
+
+// 带选项
+model.playAnimation('Run', {
+  loop: true,          // 是否循环（默认 true）
+  repetitions: 3,      // 循环次数（默认 Infinity）
+  timeScale: 1.5,      // 播放速度（默认 1）
+  clampWhenFinished: true, // 播放结束后停留在最后一帧（默认 false）
+});
+```
+
+#### `playAllAnimations(options?)`
+
+播放模型所有内置动画。参数同 `playAnimation`。
+
+```typescript
+model.playAllAnimations({ timeScale: 2 });
+```
+
+#### `stopAnimation(nameOrIndex?)`
+
+停止指定动画。不传参时停止所有动画。
+
+```typescript
+model.stopAnimation('Walk'); // 停止指定动画
+model.stopAnimation();       // 停止所有动画
+```
+
+#### `updateAnimation(delta)`
+
+推进动画时间，需在渲染循环中调用。`delta` 为帧间隔时间（秒），可从 Viewer 事件的 `delta` 属性获取。
+
+```typescript
+viewer.addEventListener('beforeRender', (e) => {
+  model.updateAnimation(e.delta);
+});
+```
+
 ### 清除缓存
 
 可通过 `Model` 类的静态方法手动清除内部缓存：

package/docs/api-render-pipeline.md

@@ -0,0 +1,114 @@
+# RenderPipeline API（后处理管线）
+
+`viewer.renderPipeline` 管理渲染后处理链，内置 Bloom、SSGI、TRAA 支持，并提供自定义后处理覆盖机制。
+
+## 渲染节点图
+
+```
+Stage 1: pass(scene, camera) + MRT（按需配置 output/emissive/normal/velocity）
+    ↓
+Stage 2: 后处理链（二选一）
+    ├─ 内置模式: SSGI → Bloom（按启用状态组合）
+    └─ 自定义模式: outputComposer(scenePass) → Node
+    ↓
+Stage 3: TRAA 时间抗锯齿
+    ↓
+Stage 4: Overlay Passes（blendColor 叠加 ViewerHelper 等）
+    ↓
+outputNode = 最终结果
+```
+
+## 属性
+
+| 属性 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `scenePass` | `PassNode` | 场景渲染通道节点，`pass(scene, camera)` 的返回值。 |
+| `needsUpdateOutputNode` | `boolean` | 标记输出节点需要在下一帧重建。 |
+
+## Bloom
+
+基于 emissive MRT 通道的泛光效果。
+
+```typescript
+// 开启 Bloom
+viewer.renderPipeline.enableBloom({ strength: 1.5, radius: 0.4, threshold: 0.2 });
+
+// 运行时更新参数
+viewer.renderPipeline.updateBloom({ strength: 2.0 });
+
+// 关闭 Bloom
+viewer.renderPipeline.disableBloom();
+```
+
+### `BloomConfig`
+
+| 属性 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :----- | :--- |
+| `strength` | `number` | `1` | 泛光强度 |
+| `radius` | `number` | `0` | 泛光扩散半径 |
+| `threshold` | `number` | `0` | 亮度阈值，低于此值不产生泛光 |
+
+## SSGI（屏幕空间全局光照）
+
+> 仅支持 `PerspectiveCamera`，使用 `OrthographicCamera` 时会自动跳过并输出警告。
+
+```typescript
+// 开启 SSGI
+viewer.renderPipeline.enableSSGI({ aoIntensity: 1, giIntensity: 10 });
+
+// 运行时更新参数（直接修改 uniform，不重建节点图）
+viewer.renderPipeline.updateSSGI({ giIntensity: 20, radius: 8 });
+
+// 关闭 SSGI
+viewer.renderPipeline.disableSSGI();
+```
+
+### `SSGIConfig`
+
+| 属性 | 类型 | 默认值 | 范围 | 说明 |
+| :--- | :--- | :----- | :--- | :--- |
+| `sliceCount` | `number` | `1` | 1–4 | 半球切片数 |
+| `stepCount` | `number` | `12` | 1–32 | 每切片采样步数 |
+| `aoIntensity` | `number` | `1` | 0–4 | 环境光遮蔽强度 |
+| `giIntensity` | `number` | `10` | 0–100 | 间接漫反射强度 |
+| `radius` | `number` | `12` | 1–25 | 世界空间采样半径 |
+| `thickness` | `number` | `1` | 0.01–10 | 物体厚度（世界单位） |
+
+## TRAA（时间抗锯齿）
+
+基于运动向量的时间分辨率抗锯齿。
+
+```typescript
+// 开启 TRAA
+viewer.renderPipeline.enableTRAA();
+
+// 关闭 TRAA
+viewer.renderPipeline.disableTRAA();
+```
+
+## 自定义后处理（OutputComposer）
+
+使用 `setOutputComposer` 可完全覆盖内置后处理链，接收 `scenePass` 返回自定义的 TSL 节点。
+
+```typescript
+import { luminance, vec4 } from 'three/tsl';
+
+// 灰度滤镜
+viewer.renderPipeline.setOutputComposer((scenePass) => {
+  const color = scenePass.getTextureNode();
+  const gray = luminance(color.rgb);
+  return vec4(gray, gray, gray, 1.0);
+});
+
+// 恢复默认（清除自定义后处理）
+viewer.renderPipeline.setOutputComposer(null);
+```
+
+## Overlay Passes
+
+用于叠加辅助渲染层（如 ViewerHelper），始终在后处理链之后执行。
+
+```typescript
+viewer.renderPipeline.addOverlayPass(overlayNode);
+viewer.renderPipeline.removeOverlayPass(overlayNode);
+```

package/docs/api-viewer.md

@@ -34,6 +34,7 @@ new Viewer(options: ViewerOptions)
 | `interactionManager` | `InteractionManager`                        | 管理对象的指针事件和射线检测。                                                                                    |
 | `objectManager`      | `ObjectManager`                             | 用于按 ID 或名称注册和检索对象的工具。                                                                            |
 | `frameloop`          | `'always'` \| `'demand'`                    | 设置渲染模式。默认为 `'demand'`（仅在需要时渲染）。设置为 `'always'` 可开启持续渲染。                             |
+| `cssRenderer`        | `CSSRenderer`                               | CSS 渲染器，支持在 3D 场景中叠加 HTML 元素（CSS2D / CSS2.5D / CSS3D）。                                           |
 | `frameCount`         | `number`                                    | 待渲染帧的内部计数器，调用 `render()` 时递增。                                                                    |
 
 ## 方法
@@ -100,6 +101,36 @@ const camera = viewer.createOrthographicCamera();
 viewer.setCamera(camera);
 ```
 
+### `controls.setCameraViewpoint(viewpoint, enableTransition?)`
+
+将相机平滑过渡到指定的位置、目标和缩放。
+
+```typescript
+await viewer.controls.setCameraViewpoint({
+  position: { x: 10, y: 5, z: 10 },
+  target: { x: 0, y: 0, z: 0 },
+  zoom: 1.0,
+});
+
+// 禁用过渡动画，立即跳转
+await viewer.controls.setCameraViewpoint(viewpoint, false);
+```
+
+**参数：**
+
+| 参数               | 类型                   | 默认值  | 说明                                |
+| :----------------- | :--------------------- | :------ | :---------------------------------- |
+| `viewpoint`        | `CameraViewpointData`  | —       | 包含 `position`、`target`、`zoom`。 |
+| `enableTransition` | `boolean`              | `true`  | 是否启用平滑过渡动画。             |
+
+#### `CameraViewpointData`
+
+| 属性       | 类型       | 说明                 |
+| :--------- | :--------- | :------------------- |
+| `position` | `IVector3` | 相机位置。           |
+| `target`   | `IVector3` | 相机注视目标位置。   |
+| `zoom`     | `number`   | 相机缩放值。         |
+
 ## 调试工具
 
 ### Info
@@ -158,8 +189,10 @@ viewer.dispose();
 
 Viewer 继承自 `EventDispatcher`，会触发以下事件：
 
-- `beforeControlsUpdate`：在 `CameraControls` 更新之前触发，提供 `{ time: number }`。
-- `afterControlsUpdate`：在 `CameraControls` 更新之后触发，提供 `{ time: number }`。
-- `beforeRender`：在 `renderer.render` 调用之前立即触发，提供 `{ time: number }`。
-- `afterRender`：在 `renderer.render` 完成之后立即触发，提供 `{ time: number }`。
+- `beforeControlsUpdate`：在 `CameraControls` 更新之前触发，提供 `{ time: number; delta: number }`。
+- `afterControlsUpdate`：在 `CameraControls` 更新之后触发，提供 `{ time: number; delta: number }`。
+- `beforeRender`：在 `renderer.render` 调用之前立即触发，提供 `{ time: number; delta: number }`。
+- `afterRender`：在 `renderer.render` 完成之后立即触发，提供 `{ time: number; delta: number }`。
 - `cameraChange`：调用 `setCamera` 时触发，提供 `{ camera: Camera }`。
+
+其中 `delta` 为上一帧到当前帧的时间间隔（秒），可用于动画更新等场景。

package/docs/examples-guide.md

@@ -46,3 +46,43 @@
 - 流式传输结构化场景布局，解析场景描述（`SceneLoader`、`TopologiesLoader`）。
 - 使用相机动画（`VisionsLoader` 和 `VisionsParser`）在场景中编排预定义的飞行路径。
 - 获取复杂的节点材质，并自定义 WebGPU 专属的 TSL（Three Shading Language）节点，如 `TSLEffects.fluid()`。
+
+## 5. `test_model_animation.html`：模型内置动画
+
+[在线演示](https://u-space-phi.vercel.app/examples/test_model_animation.html)
+
+该示例演示了如何加载含内置动画的 glTF 模型，并通过 `Model` 类的动画 API 控制播放。
+
+### 核心要点：
+
+- 使用 `Model.loadAsync()` 加载带动画的 `.glb` 文件，动画片段自动初始化。
+- 使用 `viewer.frameloop = 'always'` 开启持续渲染以驱动动画。
+- 监听 `beforeRender` 事件，通过 `model.updateAnimation(e.delta)` 推进动画时间。
+- 使用 `model.playAnimation(name)` 按名称播放单个动画，`model.playAllAnimations()` 播放全部。
+- 使用 `model.stopAnimation()` 停止动画播放。
+
+## 6. `test_css_renderer.html`：CSS2D / CSS2.5D / CSS3D 渲染器
+
+该示例演示了如何在 3D 场景中叠加渲染 HTML 元素，展示三种 CSS 渲染模式的效果差异。
+
+### 核心要点：
+
+- 使用 `viewer.cssRenderer.createCSS2DObject()` 创建始终面向相机、固定屏幕尺寸的 2D 标签。
+- 使用 `viewer.cssRenderer.createCSS25DObject()` 创建面向相机但随距离缩放的 2.5D 精灵。
+- 使用 `viewer.cssRenderer.createCSS3DObject()` 创建具有完整 3D 变换的面板。
+- CSS2.5D 和 CSS3D 对象需要设置 `scale`（通常 `0.01`），因为 HTML 元素的像素尺寸远大于 3D 世界单位。
+- 渲染器采用懒加载，仅在首次创建对应类型对象时初始化。
+
+## 7. `test_postprocessing.html`：后处理效果
+
+该示例演示了 `RenderPipeline` 的内置后处理功能，包括 Bloom、SSGI、TRAA 以及自定义后处理组合器。
+
+### 核心要点：
+
+- 使用 `viewer.renderPipeline.enableBloom()` / `disableBloom()` 运行时切换 Bloom 效果。
+- 使用 `viewer.renderPipeline.updateBloom()` 实时调整 strength、radius、threshold 参数。
+- 使用 `viewer.renderPipeline.enableSSGI()` / `disableSSGI()` 切换屏幕空间全局光照。
+- 使用 `viewer.renderPipeline.updateSSGI()` 实时调整 SSGI 参数（直接修改 uniform，无需重建节点图）。
+- 使用 `viewer.renderPipeline.enableTRAA()` / `disableTRAA()` 切换时间抗锯齿。
+- 使用 `viewer.renderPipeline.setOutputComposer()` 自定义后处理链（示例中实现了灰度滤镜）。
+- 使用 `setOutputComposer(null)` 恢复默认渲染管线。

package/docs/getting-started.md

@@ -119,6 +119,18 @@ box.addEventListener('pointerleave', (e) => {
 
 这样就完成了！你现在拥有一个基础的 `u-space` 应用。
 
+## 版本信息
+
+`u-space` 导出了 `version` 常量，同时在 `window.__USPACE__` 上挂载了版本信息，方便调试和版本检查。
+
+```typescript
+import { version } from 'u-space';
+console.log(version); // e.g. '0.0.5'
+
+// 也可以通过全局变量访问
+console.log(window.__USPACE__.version);
+```
+
 ## 下一步
 
 - 深入了解 [Viewer API](./api-viewer.md)