u-space 0.0.31 → 0.0.33

package/docs/api-objects.md

@@ -256,8 +256,10 @@ await myModel.loadAsync(parameters: ModelParameters)
 | 属性         | 类型      | 默认值 | 说明                                                                                    |
 | :----------- | :-------- | :----- | :-------------------------------------------------------------------------------------- |
 | `url`        | `string`  | —      | `.gltf` 或 `.glb` 文件的 URL。                                                          |
-| `cache`      | `boolean` | `true` | 启用内存缓存。若模型已加载过，则直接从内存中获取并克隆。                                |
-| `persistent` | `boolean` | `true` | 使用浏览器 Cache API 启用持久化磁盘缓存，适合较大的模型。                               |
+| `cache`      | `boolean` | `true` | 启用内存 LRU 缓存。若同一请求已加载，则直接从内存中获取并克隆；最多保留 32 项。          |
+| `persistent` | `boolean` | `true` | 使用浏览器 Cache API 持久化模型及外部 glTF 依赖；最多保留 64 项或 512 MiB。              |
+| `cacheMode`  | `string`  | —      | 覆盖持久化缓存策略：`no-store`、`reload`、`revalidate` 或 `force-cache`。                 |
+| `cacheKey`   | `string`  | —      | 为同一 URL 指定版本化缓存身份；适用于发布后 URL 不变的模型。                              |
 
 #### 缓存示例
 
@@ -273,8 +275,14 @@ model2.loadAsync({ url: 'model.glb', cache: false });
 // 完全禁用缓存
 const model3 = new Model();
 model3.loadAsync({ url: 'model.glb', cache: false, persistent: false });
+
+// 发布新模型但 URL 保持不变时，获取网络版本并更新该版本条目
+const model4 = new Model();
+model4.loadAsync({ url: 'model.glb', cacheMode: 'reload', cacheKey: '2026-09-02' });
 ```
 
+持久化缓存保留响应类型、验证器和真实字节长度。默认无服务端缓存指令的资源可复用 7 天；到期后优先使用 `ETag` / `Last-Modified` 条件验证，断网时可回退到已存在的非空缓存。`no-store` 不读取或写入持久化缓存；`reload` 强制网络请求并更新缓存；`revalidate` 即使缓存仍新鲜也会条件验证；`force-cache` 优先返回已有的非空缓存。`Cache-Control: no-store/private` 与 `Vary: Cookie/*` 响应不会写入缓存。空缓存、截断的外部 buffer、解析失败或缓存命中时未解码的贴图会删除相关缓存资源并重新请求一次。请求头、credentials 模式和 `cacheKey` 共同参与缓存身份，避免不同授权请求或版本共用同一条目。
+
 ### 动画
 
 `Model` 在加载含内置动画的模型（如 glTF/FBX）后，会自动初始化 `AnimationMixer` 并收集 `AnimationClip`。
@@ -372,6 +380,7 @@ myModel.setMaterial(new MeshStandardMaterial({ color: 0xff0000 }));
 
 - `Model.clearMemoryCache()`：清除运行时内存缓存。
 - `await Model.clearPersistentCache()`：完全清除浏览器中 `u-space` 模型的持久化缓存。
+- `await ModelLoaderManager.deletePersistentCache(url, { cacheKey })`：仅删除指定 URL 与版本身份的持久化缓存。
 
 ## 网格
 

package/docs/changelog.md

@@ -2,6 +2,23 @@
 
 ## 未发布
 
+## 0.0.33
+
+### 修复与优化
+
+- **模型持久化缓存**：主线程与 decode Worker 统一使用带版本、容量和响应元数据的 Cache Storage 策略，缓存项记录真实 `Content-Length`；模型及外部 glTF buffer/贴图支持过期与 `ETag` / `Last-Modified` 条件验证、离线旧缓存、授权请求隔离和损坏缓存单次自愈。调用方可通过 `cacheMode` 跳过、刷新、重验或强制读取缓存，通过 `cacheKey` 隔离同一 URL 的模型版本并精确删除目标缓存。对象内存缓存改为 32 项 LRU，磁盘缓存限制为 64 项或 512 MiB，并遵循 `no-store/private` 与敏感 `Vary` 响应。
+- **UManager 示例**：目标对象不存在、不是 Mesh 或使用多材质时，示例不再直接写入材质属性而导致页面报错。
+
+## 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 +36,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.33`。Vercel 文档部署会继续把 `__VERSION__` 占位符替换为 `package.json` 中的版本号，源码里的 `0.0.33` 作为直接托管 `examples/` 时的 fallback。
 
 插件示例可以在页面加载 `importmap.js` 前通过 `window.__IMPORTS__` 声明额外依赖。将 `u-space/plugins/<name>` 的值设为 `true` 时，`importmap.js` 会自动在本地和 CDN 路径之间切换。
 
@@ -28,7 +28,7 @@
 
 - 使用全局 `Model` 类通过 `Model.prototype.loadAsync()` 异步加载 `.glb` 文件。
 - 理解 `cache: true`（将模型节点保留在内存中，可实现即时克隆/实例化）。
-- 理解 `persistent: true`（使用 Service Worker / Cache Storage API 对实际网络请求数据进行持久化缓存）。
+- 理解 `persistent: true`（使用 Cache Storage API 持久化模型及外部 glTF 依赖，无需注册 Service Worker）。
 - 演示如何将这些异步加载的资源安全地注册到 `viewer.objectManager`。
 - 提供通过 `Model.clearMemoryCache()` 和 `Model.clearPersistentCache()` 手动清除缓存的示例。
 
@@ -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)
 

package/docs/getting-started.md

@@ -1,123 +1,127 @@
 # 快速上手 `u-space`
 
-`u-space` 是一个基于 Three.js 的 WebGPU 3D 引擎。本指南将向你展示如何搭建一个基础的 `u-space` 应用。
+`u-space` 是一个基于 Three.js 的 WebGPU 3D 引擎。本指南使用 React、TypeScript 和 Vite 搭建一个基础应用。
 
-## 安装
+## 创建项目
 
-确保已将 `@types/three` 和 `three` 安装为对等依赖。如果你计划使用交互功能，还需要安装 `camera-controls`。
+### 1. 初始化 React + Vite
 
 ```bash
-pnpm install three camera-controls
+pnpm create vite u-space-demo --template react-ts
+cd u-space-demo
+pnpm install
 ```
 
-## 基础配置
+### 2. 安装 `u-space`
 
-以下是一个最小示例，展示如何初始化 `u-space` 的 `Viewer` 并向场景中添加一个可交互对象。
+```bash
+pnpm add u-space three camera-controls
+pnpm add -D @types/three
+```
 
-### 1. HTML 结构
+Vite 会直接解析 npm 包及 `three/webgpu`，不需要额外配置模块映射。
 
-创建一个容纳 3D 查看器的元素。
+## 编写场景组件
 
-```html
-<!DOCTYPE html>
-<html lang="zh">
-  <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>
-    <!-- 脚本放这里 -->
-  </body>
-</html>
-```
+### 1. 替换 `src/App.tsx`
 
-### 2. Import Maps
+下面的组件会初始化 `Viewer`、添加一个可交互的立方体，并在 React 组件卸载时释放资源。
 
-由于 `u-space` 依赖 Three.js 的 WebGPU 特性，建议配置 Import Map 以解析 Three.js 的 WebGPU 构建版本。
+```tsx
+import { useEffect, useRef } from 'react';
+import { BoxGeometry, Color, GridHelper, MeshBasicMaterial } from 'three/webgpu';
+import { BaseMesh, Viewer } from 'u-space';
 
-```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>
-```
+export default function App() {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    let viewer: Viewer | undefined;
+    let cancelled = false;
+
+    async function setup() {
+      const nextViewer = new Viewer({
+        el: container,
+        rendererOptions: { forceWebGL: false },
+      });
+      await nextViewer.init();
+
+      // 兼容 React StrictMode 在开发环境中的重复挂载检查
+      if (cancelled) {
+        nextViewer.dispose();
+        return;
+      }
 
-### 3. 初始化 Viewer 并添加对象
+      nextViewer.scene.background = new Color(0x666666);
+      nextViewer.scene.add(new GridHelper(10, 10));
 
-初始化 `Viewer` 并向场景中添加一个基础 Three.js 对象。
+      const material = new MeshBasicMaterial({ color: 0xff0000 });
+      const box = new BaseMesh(new BoxGeometry(1, 1, 1), material);
+      box.position.set(0, 0.5, 0);
+      nextViewer.scene.add(box);
 
-```html
-<script type="module">
-  import { Color, GridHelper, Mesh, BoxGeometry, MeshBasicMaterial } from 'three/webgpu';
-  import { Viewer } from 'u-space';
+      nextViewer.interactionManager.pointerMoveEventsEnabled = true;
 
-  const app = document.getElementById('app');
+      box.addEventListener('click', ({ event }) => {
+        console.log('点击位置：', event.intersect?.point);
+        material.color.set(Math.random() * 0xffffff);
+        void nextViewer.render();
+      });
 
-  // 初始化查看器
-  const viewer = new Viewer({
-    el: app,
-    rendererOptions: { forceWebGL: false }, // 优先使用 WebGPU
-  });
-  await viewer.init();
+      box.addEventListener('pointerenter', () => {
+        document.body.style.cursor = 'pointer';
+      });
 
-  // 设置背景颜色
-  viewer.scene.background = new Color(0x666666);
+      box.addEventListener('pointerleave', () => {
+        document.body.style.cursor = 'default';
+      });
 
-  // 添加网格辅助线
-  const gridHelper = new GridHelper(10, 10);
-  viewer.scene.add(gridHelper);
+      viewer = nextViewer;
+      void viewer.render();
+    }
+
+    void setup();
 
-  // 添加一个立方体
-  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);
+    return () => {
+      cancelled = true;
+      document.body.style.cursor = 'default';
+      viewer?.dispose();
+    };
+  }, []);
 
-  // 渲染场景
-  viewer.render();
-</script>
+  return <div ref={containerRef} className="viewer" />;
+}
 ```
 
-### 4. 启用交互
-
-`u-space` 内置了 `InteractionManager`，可以轻松为 3D 对象添加事件监听。
-
-```javascript
-// 启用指针移动事件（pointerenter / pointerleave 需要此开关）
-viewer.interactionManager.pointerMoveEventsEnabled = true;
-
-// 添加点击事件
-box.addEventListener('click', (e) => {
-  console.log('点击位置：', e.event.intersect.point);
-  material.color.set(Math.random() * 0xffffff);
-  viewer.render(); // 请求新一帧渲染
-});
-
-// 添加悬停事件
-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();
-});
+`BaseMesh` 已包含 `u-space` 交互事件类型，因此可以直接监听 `click`、`pointerenter` 和 `pointerleave`。
+
+### 2. 替换 `src/index.css`
+
+```css
+html,
+body,
+#root,
+.viewer {
+  width: 100%;
+  height: 100%;
+  margin: 0;
+}
+
+body {
+  overflow: hidden;
+}
+```
+
+### 3. 启动开发服务器
+
+```bash
+pnpm dev
 ```
 
-这样就完成了！你现在拥有一个基础的 `u-space` 应用。
+打开 Vite 输出的本地地址，即可看到并操作 `u-space` 场景。
 
 ## 版本信息
 
@@ -125,7 +129,7 @@ box.addEventListener('pointerleave', (e) => {
 
 ```typescript
 import { version } from 'u-space';
-console.log(version); // e.g. '0.0.31'
+console.log(version); // e.g. '0.0.33'
 
 // 也可以通过全局变量访问
 console.log(window.__USPACE__.version);

package/docs/index.md

@@ -41,7 +41,7 @@ features:
 | [Interactions](./api-interactions) | 交互管理：射线检测、鼠标/触摸事件、框选 |
 | [Managers](./api-managers) | 对象管理、场景管理、灯光管理 |
 | [Animations](./api-animations) | 补间动画：`tweenAnimation`、`Tween`、缓动模式 |
-| [Effects](./api-effects) | 视觉特效：高亮、呼吸、线框、淡入淡出、流动、流体（TSL） |
+| [Effects](./api-effects) | 视觉特效：高亮、呼吸、线框、淡入淡出、流动、流体与可组合 Outline（TSL） |
 | [Tools](./api-tools) | 工具：测量（距离/面积/角度）、剖切（面/盒）、标注管理 |
 
 ### 插件

package/docs/mcp.md

@@ -1,6 +1,6 @@
 # u-space MCP
 
-`u-space-mcp` 是面向 `u-space` 文档的 Model Context Protocol（MCP）服务器。它把当前文档打包成只读 MCP 工具，方便 Mastra、Claude Desktop、Cursor 等 MCP 客户端在回答 `u-space` API、插件和示例问题时直接检索官方文档，包括实验性 `u-space/worker` OffscreenCanvas runtime、`OffscreenViewerHost`、top-level await `createWorkerViewer()`、Worker command/事件桥接、`ModelLoaderManager.setDecodeWorker()` + `u-space/worker/model-decoder` 嵌套静态模型解码、transferable/ACK backpressure、普通图片超过 WebGPU `8192` 上限时的解码前缩放、Three.js 原生静态场景矩阵策略及其与 `setEditableBatching()` 的组合；核心 `src/batches` 导出的 `ModelInstancedLayer` 与 `EditableGeometryBatchLayer`；`u-manager` 的 `UManagerLoader` 一体化加载入口、`SceneLoader` 语义去重、path-based model instancing 和 scene-specific editable batching adapter、Semantic/Facilities API，以及 atmosphere 和 fire 插件的 WebGPU 效果。
+`u-space-mcp` 是面向 `u-space` 文档的 Model Context Protocol（MCP）服务器。它把当前文档打包成只读 MCP 工具，方便 Mastra、Claude Desktop、Cursor 等 MCP 客户端在回答 `u-space` API、插件和示例问题时直接检索官方文档，包括实验性 `u-space/worker` OffscreenCanvas runtime、`OffscreenViewerHost`、top-level await `createWorkerViewer()`、Worker command/事件桥接、`ModelLoaderManager.setDecodeWorker()` + `u-space/worker/model-decoder` 嵌套静态模型解码、transferable/ACK backpressure、普通图片超过 WebGPU `8192` 上限时的解码前缩放、Three.js 原生静态场景矩阵策略及其与 `setEditableBatching()` 的组合；核心 `src/batches` 导出的 `ModelInstancedLayer` 与 `EditableGeometryBatchLayer`；`TSLEffects.outline()` 可组合描边和 `InstanceObject` bounds proxy；`u-manager` 的 `UManagerLoader` 一体化加载入口、`SceneLoader` 语义去重、path-based model instancing 和 scene-specific editable batching adapter、Semantic/Facilities API，以及 atmosphere 和 fire 插件的 WebGPU 效果。
 
 ## 安装与启动
 
@@ -86,7 +86,7 @@ export const codingAgent = new Agent({
 
 ## 示例检索
 
-MCP 文档索引包含 `examples/test_umanager_loader.html`、`examples/test_umanager_dynamic_instances.html`、`examples/test_umanager2.html` 和 `examples/offscreen/test_umanager2_offscreen.html` 的说明。检索 `UManagerLoader example`、`test_umanager_loader` 或 `UManagerLoader 用法` 可以找到一体化加载示例；检索 `dynamic instances`、`getInstanceById` 或 `test_umanager_dynamic_instances` 可以找到运行时实例编辑示例；检索 `setEditableBatching`、`SceneEditableBatchLayer`、`SceneEditableBatchFallback`、`editable batching`、`materialize` 或 `test_umanager2` 可以找到大型静态场景合批及其与 `SceneInstancedLayer` fallback 的关系；检索 `OffscreenCanvas`、`OffscreenViewerHost`、`host.init`、`initialized`、`ready`、`createWorkerViewer`、`ModelLoaderManager.setDecodeWorker`、`model-decoder`、`decode Worker`、`transferable`、`ACK backpressure`、`ImageBitmapLoader`、`maxTextureDimension2D`、`oversized texture`、`top-level await`、`u-space/worker`、`Worker WebGPU` 或 `test_umanager2_offscreen` 可以找到 Worker 渲染、嵌套静态模型解码、生命周期、事件/command 桥接、超大贴图缩放、editable batching、pipeline 预热和主线程/GPU 性能边界。
+MCP 文档索引包含 `examples/test_outline.html`、`examples/test_umanager_loader.html`、`examples/test_umanager_dynamic_instances.html`、`examples/test_umanager2.html` 和 `examples/offscreen/test_umanager2_offscreen.html` 的说明。检索 `TSLEffects.outline`、`outline effect`、`instanceBoundsProxy` 或 `test_outline` 可以找到描边 API 与交互示例；检索 `UManagerLoader example`、`test_umanager_loader` 或 `UManagerLoader 用法` 可以找到一体化加载示例；检索 `dynamic instances`、`getInstanceById` 或 `test_umanager_dynamic_instances` 可以找到运行时实例编辑示例；检索 `setEditableBatching`、`SceneEditableBatchLayer`、`SceneEditableBatchFallback`、`editable batching`、`materialize` 或 `test_umanager2` 可以找到大型静态场景合批及其与 `SceneInstancedLayer` fallback 的关系；检索 `OffscreenCanvas`、`OffscreenViewerHost`、`host.init`、`initialized`、`ready`、`createWorkerViewer`、`ModelLoaderManager.setDecodeWorker`、`model-decoder`、`decode Worker`、`transferable`、`ACK backpressure`、`ImageBitmapLoader`、`maxTextureDimension2D`、`oversized texture`、`top-level await`、`u-space/worker`、`Worker WebGPU` 或 `test_umanager2_offscreen` 可以找到 Worker 渲染、嵌套静态模型解码、生命周期、事件/command 桥接、超大贴图缩放、editable batching、pipeline 预热和主线程/GPU 性能边界。
 
 ## OffscreenCanvas Worker 检索范围
 
@@ -119,6 +119,17 @@ MCP 文档索引会同步 `docs/api-objects.md` 中的核心 `InstanceObject` AP
 | `FacilityInstancedLayer` | `SemanticGroup.facilityLayer` / `SemanticGroup.getDefaultFacilityLayer()`、`getInstances()`、`getInstanceById()`、`reserveBatch()`、`addInstance()` / `addInstances()`、`removeInstance()` / `removeInstances()`（支持单个 `instanceId` 字符串）、`removeBatch()`、`clearBatches()`、batch 创建条件、`setInstanceCulling()`、动态 Facilities batch、可选按相机视锥压缩 active instances、可选 `minScreenRadius` 屏幕尺寸裁剪、dirty-driven instance buffer 同步和 raycast hit remap。 |
 | `Facilities` | `SemanticLoader` 解析、`FloorMesh.getFacilityById()`、`FacilityInstanceObject.setInstanceOpacity()`、普通 `Model` fallback wrapper 与 scene-level instancing 的一致 API；`SemanticGroup` / `BuildingGroup` / `FloorMesh` 查询使用对象语义 ID、实例 `instanceId` 或显式别名，不扫描 `userData` ID。 |
 
+## Effects 检索范围
+
+MCP 文档索引会同步 `docs/api-effects.md` 中的 `MaterialEffects` / `TSLEffects` API，以及 `docs/examples-guide.md` 中的 Outline 示例。客户端可以直接检索以下关键词：
+
+| 关键词 / API | 可检索内容 |
+| :----------- | :--------- |
+| `TSLEffects.outline` / `TSLOutlineEffect` | 通过 `RenderPipeline.addOutputEffect()` 接入描边、`setSelectedObjects()` 替换选择、`update()` 动态调参，以及 `removeOutputEffect()` 后 `dispose()` 的完整生命周期。 |
+| `TSLOutlineOptions` | 可见/隐藏边缘颜色、强度、厚度、Glow、降采样比例，以及 `instanceBoundsProxy`、padding 和最小尺寸默认值。 |
+| `InstanceObject outline` / `instanceBoundsProxy` | 优先使用实例的实际渲染对象或逻辑对象渲染子树；都不存在时由世界包围盒创建不可见代理，并随 dirty callback 更新。 |
+| `test_outline` | Box、Sphere 与核心 `InstanceObject` 的交互选择、实时参数调整和 output-effect 资源释放示例。 |
+
 ## fire 检索范围
 
 MCP 文档索引会同步 `docs/api-plugin-fire.md` 中的 FireEffect API、参数和示例。客户端可以直接检索以下关键词：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-space",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "type": "module",
   "types": "dist/src/index.d.ts",
   "module": "dist/index.js",

package/dist/modelDecodeProtocol-D1Apm9iG.cjs

@@ -1 +0,0 @@
-"use strict";function h(n){const r=n.nodes??[];if(r.length>1e5)throw new Error(`Decoded glTF contains ${r.length} nodes; the safe limit is 100000.`);const D=new Uint8Array(r.length);for(let e=0;e<r.length;e++){const d=r[e].children??[],c=new Set;for(const o of d){if(!Number.isInteger(o)||o<0||o>=r.length)throw new Error(`Decoded glTF node ${e} references invalid child ${o}.`);if(c.has(o))throw new Error(`Decoded glTF node ${e} repeats child ${o}.`);if(c.add(o),D[o]++,D[o]>1)throw new Error(`Decoded glTF node ${o} has multiple parents.`)}}const t=new Uint8Array(r.length),E=(e,d)=>{if(d>512)throw new Error("Decoded glTF node graph exceeds the safe depth of 512.");if(t[e]===1)throw new Error(`Decoded glTF node graph contains a cycle at ${e}.`);if(t[e]!==2){t[e]=1;for(const c of r[e].children??[])E(c,d+1);t[e]=2}};for(let e=0;e<r.length;e++)E(e,1);const s=n.scene??0,l=n.scenes?.[s];if(!l)throw new Error(`Decoded glTF references missing scene ${s}.`);const i=new Set;for(const e of l.nodes??[]){if(!Number.isInteger(e)||e<0||e>=r.length)throw new Error(`Decoded glTF scene ${s} references invalid node ${e}.`);if(i.has(e))throw new Error(`Decoded glTF scene ${s} repeats root node ${e}.`);if(i.add(e),D[e]>0)throw new Error(`Decoded glTF scene root ${e} is also referenced as a child.`)}}class a extends Error{name="UnsupportedModelDecodeError";constructor(r){super(r)}}exports.MODEL_DECODE_PROTOCOL_VERSION=3;exports.UnsupportedModelDecodeError=a;exports.validateDecodedGltfNodeGraph=h;

package/dist/modelDecodeProtocol-wDB7ksYw.js

@@ -1,56 +0,0 @@
-const h = 3;
-function a(n) {
-  const r = n.nodes ?? [];
-  if (r.length > 1e5)
-    throw new Error(
-      `Decoded glTF contains ${r.length} nodes; the safe limit is 100000.`
-    );
-  const D = new Uint8Array(r.length);
-  for (let e = 0; e < r.length; e++) {
-    const c = r[e].children ?? [], d = /* @__PURE__ */ new Set();
-    for (const o of c) {
-      if (!Number.isInteger(o) || o < 0 || o >= r.length)
-        throw new Error(`Decoded glTF node ${e} references invalid child ${o}.`);
-      if (d.has(o))
-        throw new Error(`Decoded glTF node ${e} repeats child ${o}.`);
-      if (d.add(o), D[o]++, D[o] > 1)
-        throw new Error(`Decoded glTF node ${o} has multiple parents.`);
-    }
-  }
-  const t = new Uint8Array(r.length), i = (e, c) => {
-    if (c > 512)
-      throw new Error(
-        "Decoded glTF node graph exceeds the safe depth of 512."
-      );
-    if (t[e] === 1)
-      throw new Error(`Decoded glTF node graph contains a cycle at ${e}.`);
-    if (t[e] !== 2) {
-      t[e] = 1;
-      for (const d of r[e].children ?? []) i(d, c + 1);
-      t[e] = 2;
-    }
-  };
-  for (let e = 0; e < r.length; e++) i(e, 1);
-  const s = n.scene ?? 0, l = n.scenes?.[s];
-  if (!l) throw new Error(`Decoded glTF references missing scene ${s}.`);
-  const E = /* @__PURE__ */ new Set();
-  for (const e of l.nodes ?? []) {
-    if (!Number.isInteger(e) || e < 0 || e >= r.length)
-      throw new Error(`Decoded glTF scene ${s} references invalid node ${e}.`);
-    if (E.has(e))
-      throw new Error(`Decoded glTF scene ${s} repeats root node ${e}.`);
-    if (E.add(e), D[e] > 0)
-      throw new Error(`Decoded glTF scene root ${e} is also referenced as a child.`);
-  }
-}
-class f extends Error {
-  name = "UnsupportedModelDecodeError";
-  constructor(r) {
-    super(r);
-  }
-}
-export {
-  h as M,
-  f as U,
-  a as v
-};