u-space 0.0.5 → 0.0.9

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,14 @@ export interface FlyToBoxOptions {
 }
 export interface FlyToObjectOptions extends FlyToBoxOptions {
 }
+export interface FlyToOptions {
+    enableTransition?: boolean;
+}
+export interface CameraViewpointData {
+    position: IVector3;
+    target: IVector3;
+    zoom: number;
+}
 export declare class CameraControls extends CameraControlsBase {
     constructor(...args: ConstructorParameters<typeof CameraControlsBase>);
     /**
@@ -16,4 +25,25 @@ export declare class CameraControls extends CameraControlsBase {
     absoluteRotations(): void;
     flyToBox(box: Box3, options?: FlyToBoxOptions): Promise<boolean>;
     flyToObject(object: Object3D, options?: FlyToObjectOptions): Promise<boolean>;
+    /**
+     * Fly camera to a specific position and look-at target.
+     */
+    flyTo(position: IVector3, target: IVector3, options?: FlyToOptions): Promise<void>;
+    /**
+     * Get the current camera viewpoint data (position, target, zoom).
+     */
+    getCameraViewpoint(): CameraViewpointData;
+    /**
+     * Lock camera controls (disable all user interaction).
+     */
+    lock(): void;
+    /**
+     * Unlock camera controls (re-enable user interaction).
+     */
+    unlock(): void;
+    /**
+     * Switch between 2D top-down and 3D perspective views.
+     */
+    setViewMode(mode: '2d' | '3d', enableTransition?: boolean): Promise<void>;
+    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

@@ -1,16 +1,32 @@
-import { EventDispatcher, WebGPURenderer, Scene, PerspectiveCamera, Timer, OrthographicCamera } from 'three/webgpu';
+import { EventDispatcher, WebGPURenderer, Scene, PerspectiveCamera, Timer, OrthographicCamera, type ColorRepresentation, type Texture } from 'three/webgpu';
 import { InteractionManager } from '../interactions';
 import { ObjectManager } from '../managers';
 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 {
     el: HTMLElement;
     rendererOptions?: ViewerRendererOptions;
 }
+export interface ScreenshotOptions {
+    width?: number;
+    height?: number;
+    type?: 'image/png' | 'image/jpeg' | 'image/webp';
+    quality?: number;
+}
+export interface FogOptions {
+    color?: ColorRepresentation;
+    near?: number;
+    far?: number;
+}
+export interface FogExp2Options {
+    color?: ColorRepresentation;
+    density?: number;
+}
 export interface ViewerEventMap {
     beforeControlsUpdate: {
         time: number;
@@ -45,6 +61,7 @@ declare class Viewer extends EventDispatcher<ViewerEventMap> {
     interactionManager: InteractionManager;
     objectManager: ObjectManager;
     viewerHelper: ViewerHelper;
+    cssRenderer: CSSRenderer;
     frameCount: number;
     frameloop: 'always' | 'demand';
     constructor({ el, rendererOptions }: ViewerOptions);
@@ -58,6 +75,42 @@ declare class Viewer extends EventDispatcher<ViewerEventMap> {
     createScene(): Scene;
     createPerspectiveCamera(): PerspectiveCamera;
     createOrthographicCamera(): OrthographicCamera;
+    /**
+     * Manually trigger a resize update.
+     */
+    resize(width?: number, height?: number): void;
+    /**
+     * Capture a screenshot of the current render.
+     */
+    screenshot(options?: ScreenshotOptions): Promise<string>;
+    /**
+     * Set the scene background color, texture, or null.
+     */
+    setBackground(background: ColorRepresentation | Texture | null): void;
+    /**
+     * Set the scene environment map for reflections / IBL.
+     */
+    setEnvironment(envMap: Texture | null): void;
+    /**
+     * Enable shadow rendering.
+     */
+    enableShadow(): void;
+    /**
+     * Disable shadow rendering.
+     */
+    disableShadow(): void;
+    /**
+     * Enable linear fog.
+     */
+    enableFog(options?: FogOptions): void;
+    /**
+     * Enable exponential fog.
+     */
+    enableFogExp2(options?: FogExp2Options): void;
+    /**
+     * Disable fog.
+     */
+    disableFog(): void;
     dispose(): void;
 }
 export { Viewer };

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-camera-controls.md

@@ -0,0 +1,146 @@
+# CameraControls API
+
+`CameraControls` 是 `u-space` 对 [`camera-controls`](https://github.com/yomotsu/camera-controls) 库的扩展封装，提供相机飞行、视角切换等高级功能。通过 `viewer.controls` 访问。
+
+## 默认配置
+
+| 属性          | 默认值 | 说明                           |
+| :------------ | :----- | :----------------------------- |
+| `minDistance`  | `0.2`  | 相机最小缩放距离。             |
+| `smoothTime`  | `0.2`  | 平滑过渡时间（秒）。           |
+| `dollySpeed`  | `0.2`  | 滚轮缩放速度。                 |
+
+> 更多基础属性和方法请参考 [camera-controls 文档](https://github.com/yomotsu/camera-controls)。
+
+## 方法
+
+### `flyToBox(box, options?)`
+
+将相机飞行到指定的 `Box3` 包围盒。
+
+```typescript
+import { Box3 } from 'three/webgpu';
+
+const box = new Box3().setFromObject(myModel);
+await viewer.controls.flyToBox(box, {
+  viewpoint: 'frontTop',
+  enableTransition: true,
+  padding: 0.1,
+});
+```
+
+#### `FlyToBoxOptions`
+
+| 属性               | 类型      | 默认值       | 说明                                              |
+| :----------------- | :-------- | :----------- | :------------------------------------------------ |
+| `viewpoint`        | `string`  | `'frontTop'` | 预设视角方向，见下方视角列表。设为 `'current'` 保持当前朝向。 |
+| `enableTransition` | `boolean` | `true`       | 是否启用平滑过渡动画。                            |
+| `padding`          | `number`  | `0.1`        | 包围盒四周的留白比例。                            |
+| `cover`            | `boolean` | `false`      | 是否以覆盖模式适配（类似 CSS `object-fit: cover`）。 |
+
+**预设视角：**
+
+`top` | `bottom` | `front` | `back` | `left` | `right` | `frontTop` | `backTop` | `leftTop` | `rightTop` | `leftFrontTop` | `rightFrontTop` | `leftBackTop` | `rightBackTop` | `current`
+
+### `flyToObject(object, options?)`
+
+将相机飞行到指定对象的包围盒。参数同 `flyToBox`。
+
+```typescript
+await viewer.controls.flyToObject(myModel, { viewpoint: 'rightFrontTop' });
+```
+
+### `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`   | 相机缩放值。         |
+
+### `flyTo(position, target, options?)`
+
+将相机飞行到指定的位置和注视目标。
+
+```typescript
+await viewer.controls.flyTo(
+  { x: 10, y: 8, z: 10 },
+  { x: 0, y: 0, z: 0 },
+  { enableTransition: true },
+);
+```
+
+**参数：**
+
+| 参数               | 类型       | 默认值 | 说明                    |
+| :----------------- | :--------- | :----- | :---------------------- |
+| `position`         | `IVector3` | —      | 相机目标位置。          |
+| `target`           | `IVector3` | —      | 相机注视目标。          |
+| `enableTransition` | `boolean`  | `true` | 是否启用平滑过渡动画。 |
+
+### `getCameraViewpoint()`
+
+获取当前相机的视角数据，返回 `CameraViewpointData`。与 `setCameraViewpoint` 对应，方便保存/恢复视角。
+
+```typescript
+const viewpoint = viewer.controls.getCameraViewpoint();
+console.log(viewpoint.position, viewpoint.target, viewpoint.zoom);
+
+// 稍后恢复
+await viewer.controls.setCameraViewpoint(viewpoint);
+```
+
+### `lock()` / `unlock()`
+
+锁定或解锁相机控制（禁用/启用所有用户交互）。
+
+```typescript
+viewer.controls.lock();   // 禁止用户操作相机
+viewer.controls.unlock(); // 恢复用户操作
+```
+
+### `setViewMode(mode, enableTransition?)`
+
+在 2D 俯视图和 3D 透视图之间切换。2D 模式会将相机旋转到正上方，并锁定极角。
+
+```typescript
+await viewer.controls.setViewMode('2d'); // 切换到 2D 俯视模式
+await viewer.controls.setViewMode('3d'); // 切换回 3D 模式
+```
+
+**参数：**
+
+| 参数               | 类型              | 默认值 | 说明                    |
+| :----------------- | :---------------- | :----- | :---------------------- |
+| `mode`             | `'2d'` \| `'3d'` | —      | 视图模式。              |
+| `enableTransition` | `boolean`         | `true` | 是否启用平滑过渡动画。 |
+
+### `absoluteRotations()`
+
+将方位角（azimuth）归一化到 `[-π, π]` 范围内，避免相机在飞行过渡时产生多余旋转。在 `flyToBox` 内部自动调用。
+
+```typescript
+viewer.controls.absoluteRotations();
+```

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,120 @@
 # 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` 和 `depthWrite` 状态
 
-为对象中所有网格应用颜色/透明度高亮。使用 `userData` 和 TSL 节点图，多个对象可共享同一节点图实例，各自保持独立状态。
+### `MaterialEffects.highlightColor(object, options?)`
+
+为对象中所有网格应用颜色/透明度高亮。
 
 ```typescript
 import { MaterialEffects } from 'u-space';
 
-// 以 50% 透明度高亮为红色
-MaterialEffects.highlight(myModel, {
-  enabled: true,
+// 以 50% 透明度高亮为红色（叠加模式）
+MaterialEffects.highlightColor(myModel, {
   color: 0xff0000,
   opacity: 0.5,
   overwrite: false, // false = 叠加（相乘），true = 完全替换颜色
 });
 
-// 禁用高亮
-MaterialEffects.highlight(myModel, { enabled: false });
+// 半透明效果
+MaterialEffects.highlightColor(myModel, { opacity: 0.3 });
+
+// X 光效果（替换颜色 + 关闭深度写入）
+MaterialEffects.highlightColor(myModel, {
+  color: 0x0088ff,
+  opacity: 0.25,
+  overwrite: true,
+  depthWrite: false,
+});
+
+// 支持数组
+MaterialEffects.highlightColor([model1, model2], { color: 0x00ff00 });
 ```
 
-### `HighlightOptions`
+#### `HighlightColorOptions`
 
 | 属性        | 类型                  | 默认值      | 说明                                                                         |
 | :---------- | :-------------------- | :---------- | :--------------------------------------------------------------------------- |
-| `enabled`   | `boolean`             | `true`      | 启用或禁用高亮特效。                                                         |
-| `color`     | `ColorRepresentation` | `0xff0000`  | 高亮颜色。                                                                   |
-| `opacity`   | `number`              | `0.5`       | 高亮时材质的透明度。                                                         |
-| `overwrite` | `boolean`             | `false`     | `false` = 与原始颜色相乘（叠加）；`true` = 完全替换颜色。                    |
+| `color`      | `ColorRepresentation` | `0xff0000`  | 高亮颜色。                                                                   |
+| `opacity`    | `number`              | `0.5`       | 高亮时材质的透明度。                                                         |
+| `overwrite`  | `boolean`             | `false`     | `false` = 与原始颜色相乘（叠加）；`true` = 完全替换颜色。                    |
+| `depthWrite` | `boolean`             | —           | 可选。设为 `false` 可产生 X 光透视效果。不设置时保持原始值。                  |
+
+### `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);
+```
+
+### `MaterialEffects.wireframe(object, enabled?)`
+
+开启或关闭线框渲染模式。
+
+```typescript
+MaterialEffects.wireframe(myModel);           // 开启线框
+MaterialEffects.wireframe(myModel, false);    // 关闭线框
+MaterialEffects.removeWireframe(myModel);     // 等同于 wireframe(obj, false)
+```
+
+### `MaterialEffects.fadeIn(object, options?)` / `MaterialEffects.fadeOut(object, options?)`
+
+淡入/淡出动画效果。返回 `Promise`，在动画完成后 resolve。淡出后对象材质保持透明状态。
+
+```typescript
+// 淡出
+await MaterialEffects.fadeOut(myModel, { duration: 1000 });
+
+// 淡入
+await MaterialEffects.fadeIn(myModel, { duration: 500 });
+```
+
+> 动画期间需要持续渲染，建议配合 `viewer.frameloop = 'always'` 使用。
+
+#### `FadeOptions`
 
-> **注意：** `highlight` 会在所有受影响的网格上设置 `material.transparent = true`，并注入 `colorNode`/`opacityNode`。目前不可逆，若需恢复须手动重置这些节点。
+| 属性       | 类型     | 默认值 | 说明                |
+| :--------- | :------- | :----- | :------------------ |
+| `duration` | `number` | `500`  | 动画时长（毫秒）。 |
 
 ---
 

package/docs/api-interactions.md

@@ -6,7 +6,7 @@
 
 ## 启用交互事件
 
-出于性能考虑，指针移动事件默认可能处于禁用状态。如需悬停和拖拽效果，必须显式开启。
+出于性能考虑，指针移动事件默认处于禁用状态。如需悬停和拖拽效果，必须显式开启。
 
 ```typescript
 // 启用鼠标移动事件（如 pointerenter 和 pointerleave）
@@ -46,9 +46,9 @@ myBox.addEventListener('click', (eventData) => {
 
 以下事件类型可在可交互对象上监听：
 
-- `click`：指针点击对象时触发（过滤：长按或大幅移动后忽略）。
+- `click`：指针点击对象时触发。内置智能过滤：长按（>500ms）或移动距离过大时忽略，双击时不重复触发。
 - `dblclick`：快速双击对象时触发。
-- `rightclick`：右键短按松开时触发（长按或拖拽不触发；浏览器原生上下文菜单已被阻止）。与原生 `contextmenu` 的区别在于，此事件在 `pointerup` 时派发，因此可以正确过滤相机拖拽等操作。
+- `rightclick`：右键短按松开时触发（长按或拖拽不触发；浏览器原生上下文菜单已被阻止）。在 `pointerup` 时派发，因此可以正确过滤相机拖拽等操作。
 - `pointerdown`：指针按键在对象上按下时触发。
 - `pointerup`：指针按键在对象上释放时触发。
 - `pointermove`：指针在对象上移动时触发，需要 `pointerMoveEventsEnabled = true`。
@@ -89,13 +89,40 @@ myObject.addEventListener('click', (e) => {
 
 ### 属性
 
-| 属性                       | 类型                          | 默认值  | 说明                                                       |
-| :------------------------- | :---------------------------- | :------ | :--------------------------------------------------------- |
-| `targetObjects`            | `Object3D[]`                  | `scene.children` | 射线检测的目标对象列表，默认为场景的直接子级。  |
-| `pointerMoveEventsEnabled` | `boolean`                     | `false` | 启用 `pointermove`、`pointerenter`、`pointerleave` 事件。  |
+| 属性                       | 类型                          | 默认值            | 说明                                                       |
+| :------------------------- | :---------------------------- | :---------------- | :--------------------------------------------------------- |
+| `targetObjects`            | `Object3D[]`                  | `scene.children`  | 射线检测的目标对象列表，默认为场景的直接子级。             |
+| `pointerMoveEventsEnabled` | `boolean`                     | `false`           | 启用 `pointermove`、`pointerenter`、`pointerleave` 事件。  |
 
 ### 方法
 
+#### `enable()` / `disable()`
+
+全局启用或禁用所有交互事件。禁用后不再触发任何交互事件。
+
+```typescript
+viewer.interactionManager.disable(); // 暂停交互
+viewer.interactionManager.enable();  // 恢复交互
+```
+
+#### `setInteractable(object, interactable)`
+
+控制单个对象是否可交互。设为 `false` 后该对象及其所有子对象不再参与射线检测。
+
+```typescript
+viewer.interactionManager.setInteractable(myModel, false); // 禁止交互
+viewer.interactionManager.setInteractable(myModel, true);  // 恢复交互
+```
+
+#### `addIgnore(object)` / `removeIgnore(object)`
+
+`setInteractable` 的别名。`addIgnore(obj)` 等同于 `setInteractable(obj, false)`，`removeIgnore(obj)` 等同于 `setInteractable(obj, true)`。
+
+```typescript
+viewer.interactionManager.addIgnore(helperObject);    // 忽略辅助对象
+viewer.interactionManager.removeIgnore(helperObject);  // 恢复
+```
+
 #### `setCamera(camera)`
 
 更新用于射线检测的相机。由 `viewer.setCamera()` 自动调用。
@@ -107,3 +134,76 @@ myObject.addEventListener('click', (e) => {
 ```typescript
 viewer.interactionManager.dispose();
 ```
+
+---
+
+## Selection
+
+`Selection` 提供对象选择能力，包括单选、多选、toggle 和框选（rubber-band）。
+
+```typescript
+import { Selection } from 'u-space';
+
+const selection = new Selection(viewer.renderer.domElement, viewer.scene, viewer.camera);
+```
+
+### 基础选择
+
+```typescript
+selection.select(myObject);           // 选中
+selection.select([obj1, obj2]);       // 多选
+selection.deselect(myObject);         // 取消选择
+selection.toggle(myObject);           // 切换选择状态
+selection.clear();                    // 清空选择
+selection.isSelected(myObject);       // 检查是否已选
+```
+
+### 属性
+
+| 属性            | 类型            | 说明                                |
+| :-------------- | :-------------- | :---------------------------------- |
+| `selected`      | `Set<Object3D>` | 当前已选对象集合。                  |
+| `selectedArray` | `Object3D[]`    | 当前已选对象数组。                  |
+| `targetObjects` | `Object3D[]`    | 框选时的候选对象（默认为场景子级）。 |
+
+### 框选
+
+启用后可用鼠标拖动矩形区域选择多个对象。框选覆盖层会渲染在容器元素上。
+
+```typescript
+selection.enableBoxSelection({ deep: true });   // 开启框选
+selection.disableBoxSelection();                 // 关闭框选
+```
+
+#### `BoxSelectionOptions`
+
+| 属性        | 类型      | 默认值 | 说明                            |
+| :---------- | :-------- | :----- | :------------------------------ |
+| `className` | `string`  | —      | 框选矩形的 CSS 类名。          |
+| `deep`      | `boolean` | `true` | 是否递归检测子对象。            |
+
+### 事件
+
+```typescript
+selection.addEventListener('select', (e) => {
+  console.log('新选中:', e.objects);
+});
+
+selection.addEventListener('deselect', (e) => {
+  console.log('取消选中:', e.objects);
+});
+
+selection.addEventListener('change', (e) => {
+  console.log('当前选中:', e.selected.size, '个对象');
+});
+```
+
+### 方法
+
+#### `setCamera(camera)`
+
+更新用于框选投影计算的相机。切换相机时需调用。
+
+#### `dispose()`
+
+关闭框选、移除事件监听、清空选择集。