u-space 0.0.30 → 0.0.32

package/docs/index.md

@@ -32,7 +32,7 @@ features:
 
 | 文档 | 说明 |
 | :--- | :--- |
-| [Viewer](./api-viewer) | 核心类：渲染器、场景、相机、控制器、事件，以及实验性 OffscreenCanvas Worker runtime |
+| [Viewer](./api-viewer) | 核心类：渲染器、场景、相机、控制器、事件，以及带超大贴图保护的实验性 OffscreenCanvas Worker runtime |
 | [CameraControls](./api-camera-controls) | 相机控制：飞行、视角切换、视点过渡 |
 | [CSSRenderer](./api-css-renderer) | CSS 渲染器：CSS2D / CSS2.5D / CSS3D 叠加 HTML 元素 |
 | [RenderPipeline](./api-render-pipeline) | 后处理管线：Bloom、SSGI、SSR 时空降噪、TRAA、自定义后处理 |
@@ -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/事件桥接、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`、`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 检索范围
 
@@ -94,7 +94,9 @@ MCP 文档索引包含 `examples/test_umanager_loader.html`、`examples/test_uma
 | :----------- | :--------- |
 | `OffscreenViewerHost` | 主线程 canvas 所有权、完整构造选项/方法/事件、`transferControlToOffscreen()`、pointer/wheel/resize 转发、renderer 滚动统计和 `request()` command 调用；`host.init()` / `initialized` 只等待 `viewer.init()`，业务资源完成由一次性 `ready` 表示。还包括 init canvas transfer/post 失败或初始化期间 dispose 的 Promise rejection/资源清理，以及 dispose 后忽略迟到业务消息的语义。 |
 | `createWorkerViewer` | module Worker 顶层可直接 await 的命令式入口；同步安装 host 消息监听，完成 OffscreenCanvas/`viewer.init()` 后返回 `WorkerViewerRuntime`，提供状态、事件、command、逆序 dispose 和一次性业务 ready 生命周期、ready 前 fatal cleanup、去重 ArrayBuffer transfer，以及内置 `getStats` / `getViewpoint` / `setViewpoint` / `render` 命令。 |
-| `test_umanager2_offscreen` | UManager Worker 示例启动方式、HDR/语义/场景加载、`setEditableBatching()`、`compileAsync()` 首帧预热、滚动帧率 HUD、标准透明合成、静态场景矩阵冻结/显式提交，以及默认隐藏半透明语义分析叠加层以保持楼壳原始材质的策略。 |
+| `ModelLoaderManager.setDecodeWorker` / `u-space/worker/model-decoder` | render Worker 创建第二个模型 decode Worker 的接线方式；静态 glTF/GLB/SBMX 支持范围，fetch/cache/SBMX/JSON/base64/ImageBitmap 工作边界，transferable 数据包、串行 ACK backpressure、有界贴图内容身份复用、LoadingManager URL/item 生命周期、跨域凭据隔离、节点图安全校验、完整 AbortSignal、故障回退，以及实例绑定的 Worker disposer。 |
+| `test_umanager2_offscreen` | UManager Worker 示例启动方式、HDR/语义/场景加载、默认启用嵌套模型 decode Worker、`?modelDecodeWorker=off` A/B 开关、`setEditableBatching()`、`compileAsync()` 首帧预热、滚动帧率 HUD、标准透明合成、静态场景矩阵冻结/显式提交，以及默认显示全部语义对象且设备选择/飞向/高亮不改变其他对象显隐的调试策略。 |
+| `ImageLoader` / `ImageBitmapLoader` / `maxTextureDimension2D` | Worker 普通图片加载兼容层、JPEG/PNG/GIF/WebP 编码尺寸预读、超过默认 `8192` limit 时的首次解码等比缩放、未知格式 fallback、源 bitmap 释放，以及 loader options/cache/request headers/abort 语义。 |
 | `matrixWorldAutoUpdate` / `updateMatrixWorld` / `updateWorldMatrix` | 使用 Three.js 原生 API 冻结静态 Scene，按需提交单个对象或新增子树，并通过 `viewer.invalidate()` 请求新帧；单个 `InstanceObject.updateWorldMatrix(true, false)` 或父 Group 的 `updateWorldMatrix(true, true)` 仍会触发 dirty callback、instanced buffer 同步和 editable-batch materialize，相机矩阵继续独立更新。 |
 | `OffscreenCanvas` + `setEditableBatching` | Offscreen 移走主线程解析/合并/渲染提交，editable batching 减少 draw submission；Three.js 对象必须留在 Worker，业务对象操作通过 structured-clone command 调用。 |
 
@@ -117,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/docs/release.md

@@ -7,7 +7,7 @@
 3. VitePress 文档
 4. `/examples/` 在线示例
 
-npm 发布使用 Trusted Publishing/OIDC，不保存 `NPM_TOKEN`，日常发布不再要求输入 OTP。docs 和 examples 使用同一个 Vercel production deployment；`scripts/build-vercel-docs.mjs` 会在文档构建完成后复制 `examples/`，并将发布中的 `u-space` 版本写入部署产物的 import map。
+npm 发布使用 Trusted Publishing/OIDC，不保存 `NPM_TOKEN`，日常发布不再要求输入 OTP。docs 和 examples 使用同一个 Vercel production deployment；`scripts/build-vercel-docs.mjs` 会在文档构建完成后复制 `examples/`，将发布中的 `u-space` 版本写入部署产物的 import map，并用独立 Vite 构建将 Offscreen 示例转换为浏览器可直接执行的主线程 JavaScript、module Worker 和 WASM 资源。
 
 ## 一次性配置
 
@@ -67,11 +67,11 @@ pnpm release:all patch --no-wait
 
 工作流按以下顺序执行：
 
-1. 递增 `u-space` 和 `u-space-mcp` 版本，同步 examples/docs 中的当前版本引用。
+1. 递增 `u-space` 和 `u-space-mcp` 版本，同步 examples/docs 中的当前版本引用；将更新日志的“未发布”内容归档到新的 `X.Y.Z` 版本标题，并创建新的空“未发布”区。
 2. 执行完整测试、库构建、MCP 文档索引构建和 VitePress 构建。
 3. 将版本元数据提交并推送到 `main`。
 4. 通过 npm OIDC 发布两个包；精确版本已经存在时自动跳过。
-5. 构建并部署 docs 和 examples 到 Vercel production。
+5. 构建并部署 docs 和 examples 到 Vercel production；Offscreen TypeScript 入口会通过 `examples/offscreen/vite.config.ts` 单独打包，不会以原始 `.ts` 作为线上运行入口。
 6. 推送 `vX.Y.Z` 和 `u-space-mcp-vX.Y.Z` 标签。
 
 `release-all` concurrency group 会阻止两次发布并发运行。
@@ -86,6 +86,8 @@ pnpm release:all current
 
 工作流会跳过 registry 中已经存在的精确版本，只重试尚未完成的 npm 包、Vercel 部署和标签。
 
+`current` 不会再次修改更新日志，因此重试不会生成重复的版本标题。
+
 本地旧命令 `pnpm release`、`pnpm publish:mcp` 和 `pnpm docs:deploy` 继续保留，但它们不使用 GitHub OIDC，可能请求 npm OTP 或本机 Vercel 登录。
 
 ## 参考

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-space",
-  "version": "0.0.30",
+  "version": "0.0.32",
   "type": "module",
   "types": "dist/src/index.d.ts",
   "module": "dist/index.js",
@@ -20,6 +20,10 @@
       "types": "./dist/src/worker/runtime.d.ts",
       "import": "./dist/worker/runtime.js"
     },
+    "./worker/model-decoder": {
+      "types": "./dist/src/worker/model-decoder.d.ts",
+      "import": "./dist/worker/model-decoder.js"
+    },
     "./plugins/*": "./dist/plugins/*/index.js"
   },
   "typesVersions": {
@@ -30,6 +34,9 @@
       "worker/runtime": [
         "./dist/src/worker/runtime.d.ts"
       ],
+      "worker/model-decoder": [
+        "./dist/src/worker/model-decoder.d.ts"
+      ],
       "plugins/*": [
         "./dist/plugins/*/index.d.ts"
       ]
@@ -42,6 +49,7 @@
     "build:plugins": "cross-env BUILD_TARGET=plugins vite build --mode development",
     "build": "cross-env BUILD_TARGET=all vite build --mode production && tsc",
     "example:offscreen": "vite --config examples/offscreen/vite.config.ts",
+    "build:example:offscreen": "vite build --config examples/offscreen/vite.config.ts",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",