u-space 0.0.31 → 0.0.32

package/dist/plugins/u-manager/index.js

@@ -20670,7 +20670,7 @@ class Watermarker extends Scene {
     return this.mesh.material.map ? Promise.resolve(this.mesh.material.map) : (this.#r ??= TextureLoaderManager.loadAsyncTexture(logo).then((e) => (e.colorSpace = SRGBColorSpace, e)), this.#r);
   }
 }
-const _m4 = new Matrix4(), SEMANTIC_ID_KEYS = [
+const _m4 = new Matrix4(), MAX_CONCURRENT_MODEL_LOADS = 1, SEMANTIC_ID_KEYS = [
   "Buildings",
   "Stories",
   "Walls",
@@ -20743,7 +20743,7 @@ class SceneParser {
       }
       await Promise.all(t.children.map((o) => l(o, u ?? h)));
     };
-    return await Promise.all(e.map((t) => l(t, a))), await this.#a(a), a;
+    return await Promise.all(e.map((t) => l(t, a))), await this.#n(a), a;
   }
   #r(e) {
     const n = new BaseGroup();
@@ -20790,7 +20790,7 @@ class SceneParser {
       instances: []
     }, this.#e.set(e, n)), n;
   }
-  async #a(e) {
+  async #n(e) {
     if (this.#e.size === 0) return;
     if (this.editableBatchOptions) {
       const a = new SceneEditableBatchLayer(this.editableBatchOptions);
@@ -20852,9 +20852,11 @@ class SceneLoader extends Loader {
   editableBatchOptions = null;
   _resourceData = null;
   _treeData = [];
-  #e;
+  #e = 0;
+  #r = [];
+  #t;
   constructor(e) {
-    super(), this.viewer = e, this.#e = new Watermarker(e), this.manager = new LoadingManager();
+    super(), this.viewer = e, this.#t = new Watermarker(e), this.manager = new LoadingManager();
   }
   setKey(e) {
     return this.key = e, this;
@@ -20867,19 +20869,37 @@ class SceneLoader extends Loader {
   setEditableBatching(e = !0) {
     return this.editableBatchOptions = e === !1 ? null : e === !0 ? {} : e, this;
   }
+  async #n() {
+    if (this.#e < MAX_CONCURRENT_MODEL_LOADS) {
+      this.#e++;
+      return;
+    }
+    await new Promise((e) => {
+      this.#r.push(e);
+    });
+  }
+  #i() {
+    const e = this.#r.shift();
+    e ? e() : this.#e--;
+  }
   async loadModel(e) {
-    const n = new Model();
-    this.manager.itemStart(e);
+    await this.#n();
     try {
-      await n.loadAsync({
-        url: e
-      });
-    } catch (a) {
-      throw this.manager.itemError(e), a;
+      const n = new Model();
+      this.manager.itemStart(e);
+      try {
+        await n.loadAsync({
+          url: e
+        });
+      } catch (a) {
+        throw this.manager.itemError(e), a;
+      } finally {
+        this.manager.itemEnd(e);
+      }
+      return n;
     } finally {
-      this.manager.itemEnd(e);
+      this.#i();
     }
-    return n;
   }
   async _preareTreeData() {
     if (!this.path)
@@ -20894,7 +20914,7 @@ class SceneLoader extends Loader {
     if (this._resourceData = a, l)
       if (n.encryptWith === "DEBUG")
         try {
-          this._treeData = decryptWithDebugKey(a), this.#e.enable();
+          this._treeData = decryptWithDebugKey(a), this.#t.enable();
         } catch {
           throw new Error("u-space SceneLoader: decrypt with debug key failed");
         }
@@ -20948,7 +20968,7 @@ class SceneLoader extends Loader {
     }), this.cachedIds.clear();
   }
   dispose() {
-    this.clearCache(), this.#e.dispose();
+    this.clearCache(), this.#t.dispose();
   }
 }
 class VerticalShaftMeshError extends Error {
@@ -21183,12 +21203,12 @@ class FloorSemanticInstanceObject extends InstanceObject {
     return this.#t = !0, super.setInstanceHighlight(e, l, a), this.floorMesh.setColorAt(this.semanticIndex, new Color(e)), this.floorMesh.setOpacityAt(this.semanticIndex, l), this;
   }
   clearInstanceHighlight() {
-    return this.#t ? (this.#t = !1, super.clearInstanceHighlight(), this.#a(), this) : this;
+    return this.#t ? (this.#t = !1, super.clearInstanceHighlight(), this.#n(), this) : this;
   }
   getInstanceBoundingBox(e = new Box3(), n = !1) {
     return this.floorMesh.getBoundingBoxAt(this.semanticIndex, e, n) ?? e.makeEmpty();
   }
-  #a() {
+  #n() {
     this.#e ? this.floorMesh.setColorAt(this.semanticIndex, this.#e) : this.floorMesh.resetColorAt(this.semanticIndex), this.floorMesh.setOpacityAt(this.semanticIndex, this.#r);
   }
 }
@@ -21215,7 +21235,7 @@ class FloorMesh extends BaseMesh {
   #e;
   #r;
   #t = [];
-  #a;
+  #n;
   #i;
   #o;
   #s;
@@ -21232,7 +21252,7 @@ class FloorMesh extends BaseMesh {
       Doors: this.doorsInstances,
       Windows: this.windowsInstances,
       Staircases: this.staircasesInstances
-    }, this.#a = h, this.#i = u, this.#o = o, this.#s = s, this.#u = new Mesh(), this.#u.matrixAutoUpdate = !1, this.frustumCulled = !1, this.#r.forEach((c) => {
+    }, this.#n = h, this.#i = u, this.#o = o, this.#s = s, this.#u = new Mesh(), this.#u.matrixAutoUpdate = !1, this.frustumCulled = !1, this.#r.forEach((c) => {
       const d = new FloorSemanticInstanceObject(this, c.index);
       d.name = c.name || c.id, d.visible = c.visible, d.setInstanceIdentity({
         id: c.id,
@@ -21276,13 +21296,13 @@ class FloorMesh extends BaseMesh {
     return this.getSemantics().filter((n) => n.kind === e);
   }
   getSemanticIdAt(e) {
-    return this.#n(e).id;
+    return this.#a(e).id;
   }
   getSemanticKindAt(e) {
-    return this.#n(e).kind;
+    return this.#a(e).kind;
   }
   getSemanticNameAt(e) {
-    return this.#n(e).name;
+    return this.#a(e).name;
   }
   getSemanticObjectAt(e) {
     return this.#t[e];
@@ -21337,33 +21357,33 @@ class FloorMesh extends BaseMesh {
     return typeof e == "string" ? this.getFacilityById(e) : e;
   }
   setColorAt(e, n) {
-    const a = this.#n(e);
+    const a = this.#a(e);
     return copySemanticColor(n, a.color), this.#d(e), this.#l(), this;
   }
   resetColorAt(e) {
-    const n = this.#n(e), a = n.color.w;
+    const n = this.#a(e), a = n.color.w;
     return n.color.copy(n.initialColor), n.color.w = a, this.#d(e), this.#l(), this;
   }
   getColorAt(e, n = new Vector4()) {
-    const a = this.#n(e).color;
+    const a = this.#a(e).color;
     return n.copy(a), n;
   }
   setOpacityAt(e, n) {
-    const a = this.#n(e);
+    const a = this.#a(e);
     return a.color.w = Math.max(0, Math.min(1, n)), this.#d(e), this.#l(), this;
   }
   getOpacityAt(e) {
-    return this.#n(e).color.w;
+    return this.#a(e).color.w;
   }
   setVisibleAt(e, n) {
-    const a = this.#n(e);
+    const a = this.#a(e);
     return a.visible = n, this.#g(e), this;
   }
   getVisibleAt(e) {
-    return this.#n(e).visible;
+    return this.#a(e).visible;
   }
   setMatrixAt(e, n) {
-    const a = this.#n(e);
+    const a = this.#a(e);
     return a.matrix.copy(n), a.finalMatrix.multiplyMatrices(a.baseMatrix, a.matrix), this.#y(e), this.#p(e), this;
   }
   setScaleAt(e, n, a, l) {
@@ -21377,10 +21397,10 @@ class FloorMesh extends BaseMesh {
     });
   }
   getMatrixAt(e, n = new Matrix4()) {
-    return n.copy(this.#n(e).matrix), n;
+    return n.copy(this.#a(e).matrix), n;
   }
   getFinalMatrixAt(e, n = new Matrix4()) {
-    return n.copy(this.#n(e).finalMatrix), n;
+    return n.copy(this.#a(e).finalMatrix), n;
   }
   computeBoundingBox() {
     this.boundingBox === null && (this.boundingBox = new Box3()), this.boundingBox.makeEmpty();
@@ -21393,11 +21413,11 @@ class FloorMesh extends BaseMesh {
       this.getBoundingSphereAt(e.index, _boundsSphere, !1) && this.boundingSphere.union(_boundsSphere);
   }
   getBoundingBoxAt(e, n = new Box3(), a = !0) {
-    const l = this.#n(e);
+    const l = this.#a(e);
     return l.geometry.boundingBox || l.geometry.computeBoundingBox(), l.geometry.boundingBox ? (n.copy(l.geometry.boundingBox).applyMatrix4(l.finalMatrix), a && (this.updateWorldMatrix(!0, !1), n.applyMatrix4(this.matrixWorld)), n) : null;
   }
   getBoundingSphereAt(e, n = new Sphere(), a = !0) {
-    const l = this.#n(e);
+    const l = this.#a(e);
     return l.geometry.boundingSphere || l.geometry.computeBoundingSphere(), l.geometry.boundingSphere ? (n.copy(l.geometry.boundingSphere), a ? (this.updateWorldMatrix(!0, !1), _boundsMatrix.multiplyMatrices(this.matrixWorld, l.finalMatrix), n.applyMatrix4(_boundsMatrix)) : n.applyMatrix4(l.finalMatrix), n) : null;
   }
   raycast(e, n) {
@@ -21414,7 +21434,7 @@ class FloorMesh extends BaseMesh {
       }
   }
   dispose() {
-    this.geometry.dispose(), Array.isArray(this.material) ? this.material.forEach((e) => e.dispose()) : this.material.dispose(), this.#a.dispose(), this.#i.dispose(), this.#o.dispose(), this.#s.dispose(), this.#r.forEach((e) => e.geometry.dispose());
+    this.geometry.dispose(), Array.isArray(this.material) ? this.material.forEach((e) => e.dispose()) : this.material.dispose(), this.#n.dispose(), this.#i.dispose(), this.#o.dispose(), this.#s.dispose(), this.#r.forEach((e) => e.geometry.dispose());
   }
   #v(e) {
     for (const [n, a] of this.facilityObjectsById)
@@ -21440,7 +21460,7 @@ class FloorMesh extends BaseMesh {
     const { facility: n } = e.userData;
     return e.instanceName ? e.instanceName : n && typeof n.Name == "string" && n.Name ? n.Name : e.name || void 0;
   }
-  #n(e) {
+  #a(e) {
     const n = this.#r[e];
     if (!n)
       throw new Error(`u-space FloorMesh: invalid semantic index ${e}.`);
@@ -21483,7 +21503,7 @@ class FloorMesh extends BaseMesh {
       n(a);
   }
   #B(e) {
-    const n = this.#n(e), a = this.#f.get(e) ?? n.matrix;
+    const n = this.#a(e), a = this.#f.get(e) ?? n.matrix;
     this.#f.has(e) || this.#f.set(e, n.matrix.clone()), a.decompose(_dummyPosition, _dummyQuaternion, _dummyScale), _dummyScale.y *= PLANISH_SCALE_Y, n.matrix.compose(_dummyPosition, _dummyQuaternion, _dummyScale), n.finalMatrix.multiplyMatrices(n.baseMatrix, n.matrix), n.geometry.boundingBox || n.geometry.computeBoundingBox(), n.geometry.boundingBox && (_box.copy(n.geometry.boundingBox).applyMatrix4(n.finalMatrix), _dummyPosition.y += this.pivot.y + getSemanticPlanishOffset(n) - _box.min.y, n.matrix.compose(_dummyPosition, _dummyQuaternion, _dummyScale), n.finalMatrix.multiplyMatrices(n.baseMatrix, n.matrix)), this.#y(e), this.#p(e);
   }
   #A(e) {
@@ -21516,21 +21536,21 @@ class FloorMesh extends BaseMesh {
     }), n.isEmpty() ? null : n;
   }
   #m(e, n) {
-    const a = this.#n(e);
+    const a = this.#a(e);
     return a.matrix.decompose(_dummyPosition, _dummyQuaternion, _dummyScale), n(_dummyScale), a.matrix.compose(_dummyPosition, _dummyQuaternion, _dummyScale), a.finalMatrix.multiplyMatrices(a.baseMatrix, a.matrix), this.#y(e), this.#p(e), this;
   }
   #d(e) {
-    this.#n(e).color.toArray(this.#a.image.data, e * 4), this.#a.needsUpdate = !0;
+    this.#a(e).color.toArray(this.#n.image.data, e * 4), this.#n.needsUpdate = !0;
   }
   #g(e) {
-    const n = this.#n(e), a = this.#i.image.data;
+    const n = this.#a(e), a = this.#i.image.data;
     a[e * 4] = n.visible ? 1 : 0, a[e * 4 + 1] = 0, a[e * 4 + 2] = 0, a[e * 4 + 3] = 1, this.#i.needsUpdate = !0;
   }
   #p(e) {
-    this.#n(e).finalMatrix.toArray(this.#o.image.data, e * 16), this.#o.needsUpdate = !0;
+    this.#a(e).finalMatrix.toArray(this.#o.image.data, e * 16), this.#o.needsUpdate = !0;
   }
   #I(e) {
-    const n = this.#n(e), a = this.#s.image.data;
+    const n = this.#a(e), a = this.#s.image.data;
     a[e * 4] = getSemanticRenderOffset(n), a[e * 4 + 1] = 0, a[e * 4 + 2] = 0, a[e * 4 + 3] = 1, this.#s.needsUpdate = !0;
   }
 }
@@ -21582,7 +21602,7 @@ class BuildingGroup extends BaseGroup {
   #e = /* @__PURE__ */ new Set();
   #r = /* @__PURE__ */ new Map();
   #t = /* @__PURE__ */ new Map();
-  #a = /* @__PURE__ */ new Map();
+  #n = /* @__PURE__ */ new Map();
   #i = /* @__PURE__ */ new Map();
   #o = /* @__PURE__ */ new Map();
   #s = /* @__PURE__ */ new Map();
@@ -21624,17 +21644,17 @@ class BuildingGroup extends BaseGroup {
     return n !== -1 && this.elevatorMeshes.splice(n, 1), rebuildObjectIndex(this.#t, this.elevatorMeshes), this.remove(e), this;
   }
   addVent(e) {
-    return this.ventMeshes.includes(e) || (this.add(e), this.ventMeshes.push(e), indexObject(this.#a, e)), this;
+    return this.ventMeshes.includes(e) || (this.add(e), this.ventMeshes.push(e), indexObject(this.#n, e)), this;
   }
   getVentAt(e) {
     return this.ventMeshes[e];
   }
   getVentById(e) {
-    return this.#a.get(e);
+    return this.#n.get(e);
   }
   removeVent(e) {
     const n = this.ventMeshes.indexOf(e);
-    return n !== -1 && this.ventMeshes.splice(n, 1), rebuildObjectIndex(this.#a, this.ventMeshes), this.remove(e), this;
+    return n !== -1 && this.ventMeshes.splice(n, 1), rebuildObjectIndex(this.#n, this.ventMeshes), this.remove(e), this;
   }
   isolateFloor(e) {
     return this.isolateFloors(getFloorReferences(e));
@@ -21703,7 +21723,7 @@ class SemanticGroup extends BaseGroup {
   #e = /* @__PURE__ */ new Set();
   #r = /* @__PURE__ */ new Map();
   #t = /* @__PURE__ */ new Map();
-  #a = /* @__PURE__ */ new Map();
+  #n = /* @__PURE__ */ new Map();
   #i = /* @__PURE__ */ new Map();
   #o = !0;
   constructor() {
@@ -21766,12 +21786,12 @@ class SemanticGroup extends BaseGroup {
     let e = this.#o || this.#i.size !== this.buildings.length;
     for (const n of this.buildings)
       n.syncFacilityIndexes(), this.#i.get(n) !== n.facilityIndexVersion && (e = !0);
-    e && (this.#t.clear(), this.#a.clear(), this.#i.clear(), this.buildings.forEach((n) => {
+    e && (this.#t.clear(), this.#n.clear(), this.#i.clear(), this.buildings.forEach((n) => {
       n.syncFacilityIndexes(), this.#i.set(n, n.facilityIndexVersion);
       for (const a of n.getFacilityIndexIds())
         this.#t.has(a) || this.#t.set(a, n);
       for (const a of n.getFacilityIndexObjects())
-        this.#a.has(a) || this.#a.set(a, n);
+        this.#n.has(a) || this.#n.set(a, n);
     }), this.#o = !1);
   }
 }
@@ -22247,7 +22267,7 @@ class SemanticParser {
         h.push(...o);
         continue;
       }
-      const r = o.map((d) => this.#a(d));
+      const r = o.map((d) => this.#n(d));
       l.addInstances(u, s, r) ? r.forEach((d, p) => {
         const v = o[p];
         this.#o(d, v.facility, a);
@@ -22257,7 +22277,7 @@ class SemanticParser {
     }
     l.children.length > 0 && n.setFacilityLayer(l), await Promise.all(h.map((u) => this.#i(u, a)));
   }
-  #a(e) {
+  #n(e) {
     const { facility: n, story: a, floorMesh: l, treeNode: t, worldMatrix: h } = e, u = new FacilityInstanceObject();
     return u.name = n.Name || t.name || "", u.visible = t.visible, u.setInstanceIdentity({
       id: n.ID,
@@ -22277,7 +22297,7 @@ class SemanticParser {
   async #i(e, n) {
     const { facility: a, story: l, treeNode: t } = e, h = await createFacilityModel(a, t, n);
     if (!h) return;
-    const u = this.#a(e);
+    const u = this.#n(e);
     u.userData.instanced = !1, Object.assign(h.userData, {
       storyId: l.ID,
       floorIndex: l.FloorIndex,

package/docs/api-effects.md

@@ -1,6 +1,6 @@
 # Effects API
 
-`u-space` 提供了两个基于 Three.js 着色语言（TSL/WebGPU 节点）的静态特效工具：`MaterialEffects` 用于为对象应用高亮、呼吸等材质特效，`TSLEffects` 用于生成动态颜色节点模式。
+`u-space` 提供了两个基于 Three.js 着色语言（TSL/WebGPU 节点）的静态特效工具：`MaterialEffects` 用于为对象应用高亮、呼吸等材质特效，`TSLEffects` 用于生成动态颜色节点模式和可组合的 Outline 输出效果。
 
 ## `MaterialEffects`
 
@@ -123,7 +123,71 @@ await MaterialEffects.fadeIn(myModel, { duration: 500 });
 
 ## `TSLEffects`
 
-静态工厂类，返回 TSL 颜色节点。将返回值赋给 `NodeMaterial` 的 `material.colorNode` 即可应用动态着色器特效。持续动画需要 `viewer.frameloop = 'always'`。
+静态工厂类。`flow()`、`breathe()` 和 `fluid()` 返回可赋给 `NodeMaterial.colorNode` 的 TSL 颜色节点；`outline()` 返回接入 `RenderPipeline` 的输出效果。持续动画需要 `viewer.frameloop = 'always'`。
+
+### `TSLEffects.outline(options?)`
+
+创建基于 Three.js `OutlineNode` 的屏幕空间描边效果。它不会修改对象材质，而是通过 `RenderPipeline.addOutputEffect()` 叠加在默认渲染结果上，因此可以与内置 Bloom、SSGI、SSR 以及其他 output effects 组合。
+
+```typescript
+import { TSLEffects } from 'u-space';
+
+const outline = TSLEffects.outline({
+  selectedObjects: [model],
+  edgeStrength: 3,
+  edgeThickness: 1.5,
+  edgeGlow: 0,
+  visibleEdgeColor: 0x00e5ff,
+  hiddenEdgeColor: 0xff4d6d,
+  downSampleRatio: 2,
+  instanceBoundsProxy: true,
+  instanceBoundsPadding: 0.05,
+});
+
+viewer.renderPipeline.addOutputEffect(outline);
+
+// 替换当前描边对象，不需要重建后处理链。
+outline.setSelectedObjects([anotherObject]);
+
+// 运行时更新样式与 InstanceObject bounds proxy 参数。
+outline.update({ edgeStrength: 4, edgeGlow: 0.25 });
+viewer.render();
+
+// 销毁前先从 RenderPipeline 移除。
+viewer.renderPipeline.removeOutputEffect(outline);
+outline.dispose();
+```
+
+#### `TSLOutlineOptions`
+
+| 属性 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `selectedObjects` | `readonly Object3D[]` | `[]` | 初始描边对象。普通 Mesh、Group 与核心 `InstanceObject` 均可传入。 |
+| `edgeStrength` | `number` | `3` | 边缘颜色强度。 |
+| `edgeThickness` | `number` | `1` | 边缘厚度。 |
+| `edgeGlow` | `number` | `0` | 描边向外扩散的发光强度。 |
+| `visibleEdgeColor` | `ColorRepresentation` | `0xffffff` | 可见边缘颜色。 |
+| `hiddenEdgeColor` | `ColorRepresentation` | `0x4e3636` | 被遮挡边缘颜色。 |
+| `downSampleRatio` | `number` | `2` | Outline pass 降采样比例；非有限值或 `<= 0` 时恢复为 `2`。值越大成本越低，但边缘精度也越低。 |
+| `instanceBoundsProxy` | `boolean` | `true` | `InstanceObject` 没有可直接描边的渲染子树时，是否用世界包围盒代理生成轮廓。 |
+| `instanceBoundsPadding` | `number` | `0` | bounds proxy 每个方向额外扩张的世界单位。 |
+| `instanceBoundsMinSize` | `number` | `0.001` | bounds proxy 每个轴向的最小尺寸，避免退化包围盒无法描边。 |
+
+#### 返回的 `TSLOutlineEffect`
+
+| 成员 | 说明 |
+| :--- | :--- |
+| `selectedObjects` | 当前逻辑选择对象的只读快照。 |
+| `outlineNode` | 当前内部 `OutlineNode`；在 RenderPipeline 首次构建前为 `null`，Scene 或 Camera 变化后可能被替换。 |
+| `setSelectedObjects(objects)` | 替换当前选择并返回自身，便于链式调用。空数组会清除描边。 |
+| `update(options)` | 更新除 `selectedObjects` 外的全部样式和 bounds proxy 选项，并返回自身。 |
+| `dispose()` | 释放内部 OutlineNode、代理 Geometry/Material 和 dirty 订阅。调用前应先 `removeOutputEffect()`。 |
+
+对于 `InstanceObject`，效果会优先描边 `getInstanceRenderObject()` 返回的可渲染对象；如果逻辑对象自身包含 Mesh/Sprite，则直接使用该对象；只有两者都不可用时才根据 `getInstanceBoundingBox()` 创建不可见 bounds proxy。代理会监听 `onInstanceRenderDirty()`，在实例显隐、变换或包围盒变化后同步，而且不会参与拾取、颜色输出或阴影。
+
+> 如果业务设置了自定义 `viewer.renderPipeline.setOutputComposer()`，RenderPipeline 会按自定义 composer 语义跳过所有 output effects，Outline 也不会显示。更新选择或参数后，`frameloop = 'demand'` 的 Viewer 需要调用 `viewer.render()` 或 `viewer.invalidate()` 请求新帧。
+
+[在线示例](https://u-space-phi.vercel.app/examples/test_outline.html)
 
 ### `TSLEffects.flow(parameters?)`
 

package/docs/changelog.md

@@ -2,6 +2,16 @@
 
 ## 未发布
 
+## 0.0.32
+
+### 修复与优化
+
+- **Offscreen 在线示例场景源** — 保留本地 `examples/scenes/飞龙吾悦广场` 及其匹配密钥；GitHub 发布流程会在 Vercel 构建前拉取真实 Git LFS 对象，构建脚本也会拒绝仅含 pointer 的场景。超过 Vercel 单文件上限的场景资源会在部署产物中拆成 90 MiB 分片，由 render/decode Worker 流式还原，既避免把 LFS pointer 当作 JSON，也不替换原场景。
+
+### 文档
+
+- **TSLEffects Outline** — 补齐 `TSLEffects.outline()`、`TSLOutlineOptions`、`TSLOutlineEffect`、RenderPipeline output-effect 接入、`InstanceObject` 渲染对象/bounds proxy 策略、资源释放、`test_outline.html` 在线示例及 MCP/LLM 检索入口。该效果最早随 `0.0.30` 发布，本次补全此前遗漏的文档发布面。
+
 ## 0.0.31
 
 ### 新增
@@ -19,6 +29,7 @@
 
 ### 新增
 
+- **TSLEffects Outline** — 新增 `TSLEffects.outline()` 可组合 output effect，支持普通 `Object3D` 与核心 `InstanceObject` 的可见/隐藏边缘描边、运行时选择和样式更新，以及在实例没有直接可描边渲染子树时使用世界包围盒代理；`examples/test_outline.html` 提供交互示例。
 - **AO 示例** — 新增 `examples/test_ao.html`，通过 SSGI 的 `giIntensity: 0` 默认开启纯 AO，并提供遮蔽强度、半径和厚度实时调节。
 - **RenderPipeline SSR** — 新增 `enableSSR()`、`updateSSR()` 和 `disableSSR()`，封装 Stochastic SSR、Temporal Reproject、Recurrent Denoise、velocity 以及双向历史反馈；提供完整 SSR 与降噪参数配置。
 - **Viewer** — 新增可选 `pixelRatio` 构造参数，省略时继续使用 `Math.min(window.devicePixelRatio, 1.5)`。

package/docs/examples-guide.md

@@ -4,7 +4,7 @@
 
 ## 运行方式与版本
 
-示例统一通过 `examples/importmap.js` 注入 Import Map。本地通过 `localhost`、`127.0.0.1`、`0.0.0.0` 或 `192.168.x.x` 访问时会加载仓库里的 `../dist/` 构建产物；在线部署或非本地域名访问时会从 jsDelivr 加载当前发布版本 `u-space@0.0.31`。Vercel 文档部署会继续把 `__VERSION__` 占位符替换为 `package.json` 中的版本号，源码里的 `0.0.31` 作为直接托管 `examples/` 时的 fallback。
+示例统一通过 `examples/importmap.js` 注入 Import Map。本地通过 `localhost`、`127.0.0.1`、`0.0.0.0` 或 `192.168.x.x` 访问时会加载仓库里的 `../dist/` 构建产物；在线部署或非本地域名访问时会从 jsDelivr 加载当前发布版本 `u-space@0.0.32`。Vercel 文档部署会继续把 `__VERSION__` 占位符替换为 `package.json` 中的版本号，源码里的 `0.0.32` 作为直接托管 `examples/` 时的 fallback。
 
 插件示例可以在页面加载 `importmap.js` 前通过 `window.__IMPORTS__` 声明额外依赖。将 `u-space/plugins/<name>` 的值设为 `true` 时，`importmap.js` 会自动在本地和 CDN 路径之间切换。
 
@@ -224,7 +224,21 @@ pnpm example:offscreen
 - 使用 `MaterialEffects.fadeOut(object)` / `fadeIn(object)` 执行淡入淡出动画。
 - 使用 `MaterialEffects.removeHighlightColor(object)` 恢复原始材质状态。
 
-## 16. `test_selection.html`：Selection 选择系统
+## 16. `test_outline.html`：TSLEffects Outline 描边
+
+[在线演示](https://u-space-phi.vercel.app/examples/test_outline.html)
+
+该示例演示 `TSLEffects.outline()` 作为 RenderPipeline output effect 对普通 Mesh、Group 和核心 `InstanceObject` 进行屏幕空间描边。
+
+### 核心要点：
+
+- 使用 `viewer.renderPipeline.addOutputEffect(outline)` 叠加 Outline，不修改原始材质，也不占用业务侧 `setOutputComposer()`。
+- 使用 `outline.setSelectedObjects()` 在 Box、Sphere、`InstanceObject`、全部对象和空选择之间切换。
+- 使用 `outline.update()` 实时调整强度、厚度、Glow 和 `instanceBoundsPadding`。
+- `InstanceObject` 有实际渲染对象时直接描边；没有可渲染子树时可通过 `getInstanceBoundingBox()` 自动生成不可见 bounds proxy。
+- 销毁时先调用 `removeOutputEffect(outline)`，再调用 `outline.dispose()` 释放 OutlineNode 与代理资源。
+
+## 17. `test_selection.html`：Selection 选择系统
 
 该示例演示了对象选择系统的单选和框选功能。
 
@@ -235,7 +249,7 @@ pnpm example:offscreen
 - 使用 `selection.enableBoxSelection()` 开启鼠标框选模式。
 - 框选模式下可配合 `viewer.controls.lock()` 避免框选与相机旋转冲突。
 
-## 17. `test_measure.html`：MeasureTool 测量工具
+## 18. `test_measure.html`：MeasureTool 测量工具
 
 该示例演示了 3D 场景中的距离、面积和角度测量。
 
@@ -246,7 +260,7 @@ pnpm example:offscreen
 - 使用 `measureTool.measureAngle(pointA, vertex, pointC)` 测量夹角。
 - 测量结果以可视化线条渲染到场景中，返回的 `MeasureResult` 包含数值和单位。
 
-## 18. `test_annotation.html`：AnnotationManager 标注管理
+## 19. `test_annotation.html`：AnnotationManager 标注管理
 
 该示例演示了 3D 标注的创建、更新和管理，配合 `CSSRenderer` 实现 HTML 浮动标签。
 
@@ -258,7 +272,7 @@ pnpm example:offscreen
 - 使用 `updateContent()` 动态更新标注内容，`updatePosition()` 移动标注位置。
 - 使用 `hideAll()` / `showAll()` 批量控制标注显隐。
 
-## 19. `test_clipping.html`：ClippingTool 剖切工具
+## 20. `test_clipping.html`：ClippingTool 剖切工具
 
 该示例演示了剖切面的创建和实时调整。
 
@@ -269,7 +283,7 @@ pnpm example:offscreen
 - 使用滑块通过 `clippingTool.setPlaneConstant()` 实时调整剖切位置。
 - 使用 `showHelper()` / `hideHelper()` 切换剖切面可视化辅助。
 
-## 20. `test_lights.html`：LightManager 灯光管理
+## 21. `test_lights.html`：LightManager 灯光管理
 
 该示例演示了灯光管理器的灯光预设和 Helper 可视化功能。
 
@@ -280,7 +294,7 @@ pnpm example:offscreen
 - 使用 `showAllHelpers()` / `hideAllHelpers()` 显示或隐藏灯光辅助可视化。
 - 每种预设会自动清除旧灯光并创建新的灯光组合。
 
-## 21. `test_fire.html`：WebGPU 体积火焰
+## 22. `test_fire.html`：WebGPU 体积火焰
 
 该示例演示了 `u-space/plugins/fire` 的 `FireEffect` 插件，封装 Three.js 官方体积火焰示例，在独立 volumetric pass 中模拟火焰和烟雾后叠加到主场景。
 
@@ -292,7 +306,7 @@ pnpm example:offscreen
 - 通过 `fire.update()` 实时调整 `fireIntensity`、`smokeLifespan`、`emitterRadius` 等参数。
 - 插件使用 RenderPipeline output effect 接入，不占用业务侧的 `setOutputComposer()`。
 
-## 22. `test_ssr.html`：SSR 时空降噪
+## 23. `test_ssr.html`：SSR 时空降噪
 
 [在线演示](https://u-space-phi.vercel.app/examples/test_ssr.html)
 
@@ -310,7 +324,7 @@ pnpm example:offscreen
 - `maxDistance` 从默认值 `0.4` 开始，保留滑块用于观察追踪距离对质量和性能的影响。
 - 移动物体继续生成 velocity，但不投射动态阴影；2048² 方向光阴影只更新一次。
 
-## 23. `test_ao.html`：环境光遮蔽
+## 24. `test_ao.html`：环境光遮蔽
 
 [在线演示](https://u-space-phi.vercel.app/examples/test_ao.html)