u-space 0.0.28 → 0.0.30

package/dist/worker/runtime.js

@@ -0,0 +1,418 @@
+import { s as W } from "../protocol-C-OMPz15.js";
+import { V as D } from "../Viewer-Cs_y7IiH.js";
+import { ImageLoader as A, Cache as z } from "three/webgpu";
+const C = /* @__PURE__ */ new WeakMap();
+class E {
+  type;
+  timeStamp = performance.now();
+  target;
+  currentTarget;
+  cancelable = !0;
+  bubbles = !0;
+  defaultPrevented = !1;
+  cancelBubble = !1;
+  immediatePropagationStopped = !1;
+  pointerId = 0;
+  pointerType = "mouse";
+  button = 0;
+  buttons = 0;
+  altKey = !1;
+  ctrlKey = !1;
+  metaKey = !1;
+  shiftKey = !1;
+  movementX = 0;
+  movementY = 0;
+  clientX = 0;
+  clientY = 0;
+  offsetX = 0;
+  offsetY = 0;
+  pageX = 0;
+  pageY = 0;
+  screenX = 0;
+  screenY = 0;
+  deltaX = 0;
+  deltaY = 0;
+  deltaZ = 0;
+  deltaMode = 0;
+  constructor(e, t) {
+    this.type = e.type, this.target = t, this.currentTarget = t;
+    for (const [r, a] of Object.entries(e))
+      r !== "type" && a !== void 0 && Reflect.set(this, r, a);
+  }
+  preventDefault() {
+    this.defaultPrevented = !0;
+  }
+  stopPropagation() {
+    this.cancelBubble = !0;
+  }
+  stopImmediatePropagation() {
+    this.cancelBubble = !0, this.immediatePropagationStopped = !0;
+  }
+  composedPath() {
+    return [this.target];
+  }
+}
+class y {
+  style = { cssText: "" };
+  innerText = "";
+  textContent = "";
+  className = "";
+  parentElement = null;
+  children = [];
+  appendChild(e) {
+    return this.children.push(e), e instanceof y && (e.parentElement = this), e;
+  }
+  removeChild(e) {
+    const t = this.children.indexOf(e);
+    return t >= 0 && this.children.splice(t, 1), e instanceof y && (e.parentElement = null), e;
+  }
+  remove() {
+    this.parentElement?.removeChild(this);
+  }
+  setAttribute() {
+  }
+  addEventListener() {
+  }
+  removeEventListener() {
+  }
+  getContext() {
+    return null;
+  }
+}
+function F(s) {
+  const e = (t) => t.toLowerCase() === "canvas" ? new OffscreenCanvas(1, 1) : new y();
+  return {
+    body: s,
+    documentElement: s,
+    pointerLockElement: null,
+    visibilityState: "visible",
+    createElement: e,
+    createElementNS: (t, r) => e(r),
+    addEventListener: s.addEventListener.bind(s),
+    removeEventListener: s.removeEventListener.bind(s),
+    exitPointerLock() {
+    }
+  };
+}
+function c(s, e, t) {
+  Object.defineProperty(s, e, {
+    configurable: !0,
+    value: t
+  });
+}
+function v(s, e, t) {
+  Object.defineProperty(s, e, {
+    configurable: !0,
+    get: t
+  });
+}
+function O(s, e) {
+  const t = {
+    size: { ...e },
+    listeners: /* @__PURE__ */ new Map(),
+    listenerWrappers: /* @__PURE__ */ new WeakMap()
+  };
+  C.set(s, t);
+  const r = s, a = {
+    cssText: "",
+    position: "relative",
+    touchAction: "none",
+    width: `${e.width}px`,
+    height: `${e.height}px`
+  }, l = (i, p) => {
+    if (!p) return;
+    let d;
+    typeof p == "function" ? d = p : (d = t.listenerWrappers.get(p) ?? ((b) => p.handleEvent(b)), t.listenerWrappers.set(p, d));
+    let h = t.listeners.get(i);
+    h || (h = /* @__PURE__ */ new Set(), t.listeners.set(i, h)), h.add(d);
+  }, u = (i, p) => {
+    if (!p) return;
+    const d = t.listeners.get(i);
+    if (d)
+      if (typeof p == "function")
+        d.delete(p);
+      else {
+        const h = t.listenerWrappers.get(p);
+        h && d.delete(h);
+      }
+  };
+  c(r, "style", a), c(r, "addEventListener", l), c(r, "removeEventListener", u), c(r, "appendChild", (i) => i), c(r, "removeChild", (i) => i), c(r, "setAttribute", () => {
+  }), c(r, "removeAttribute", () => {
+  }), c(r, "setPointerCapture", () => {
+  }), c(r, "releasePointerCapture", () => {
+  }), c(r, "hasPointerCapture", () => !1), c(r, "requestPointerLock", () => Promise.resolve()), c(r, "focus", () => {
+  }), c(r, "remove", () => {
+  }), v(r, "clientWidth", () => t.size.width), v(r, "clientHeight", () => t.size.height), v(r, "offsetWidth", () => t.size.width), v(r, "offsetHeight", () => t.size.height), v(r, "offsetTop", () => t.size.top), v(r, "offsetLeft", () => t.size.left), v(r, "clientTop", () => t.size.top), v(r, "clientLeft", () => t.size.left), v(r, "pageXOffset", () => t.size.left), v(r, "pageYOffset", () => t.size.top), v(r, "parentElement", () => r), c(r, "getBoundingClientRect", () => {
+    const { width: i, height: p, top: d, left: h } = t.size;
+    return {
+      width: i,
+      height: p,
+      top: d,
+      left: h,
+      right: h + i,
+      bottom: d + p,
+      x: h,
+      y: d,
+      toJSON: () => ({ width: i, height: p, top: d, left: h })
+    };
+  });
+  const f = F(r);
+  return c(r, "ownerDocument", f), c(r, "documentElement", r), c(r, "devicePixelRatio", e.pixelRatio), $(r, f), r;
+}
+function I(s, e) {
+  const t = C.get(s);
+  if (!t) throw new Error("The OffscreenCanvas has not been configured as a Worker DOM target.");
+  t.size = { ...e }, s.style.width = `${e.width}px`, s.style.height = `${e.height}px`, c(s, "devicePixelRatio", e.pixelRatio);
+}
+function V(s, e) {
+  const t = C.get(s);
+  if (!t) throw new Error("The OffscreenCanvas has not been configured as a Worker DOM target.");
+  const r = new E(e, s), a = [...t.listeners.get(e.type) ?? []];
+  for (const l of a)
+    if (l(r), r.immediatePropagationStopped) break;
+  return r;
+}
+function $(s, e) {
+  const t = globalThis;
+  t.window = s, t.document = e, t.getComputedStyle = () => ({ position: "relative" }), t.PointerEvent = E, t.MouseEvent = E, t.WheelEvent = E, t.Image = y;
+}
+const M = /* @__PURE__ */ new Map();
+let P = !1;
+function B() {
+  P || (P = !0, A.prototype.load = function(e, t, r, a) {
+    let l = e;
+    this.path !== void 0 && (l = this.path + l), l = this.manager.resolveURL(l);
+    const u = z.get(`image:${l}`);
+    if (this.manager.itemStart(l), u)
+      return queueMicrotask(() => {
+        t?.(u), this.manager.itemEnd(l);
+      }), u;
+    let f = M.get(l);
+    return f || (f = fetch(l).then((i) => {
+      if (!i.ok) throw new Error(`Failed to load image ${l}: ${i.status} ${i.statusText}`);
+      return i.blob();
+    }).then(
+      (i) => createImageBitmap(i, {
+        colorSpaceConversion: "none",
+        premultiplyAlpha: "none"
+      })
+    ).then((i) => (z.add(`image:${l}`, i), i)).finally(() => M.delete(l)), M.set(l, f)), f.then((i) => {
+      t?.(i), this.manager.itemEnd(l);
+    }).catch((i) => {
+      a?.(i), this.manager.itemError(l), this.manager.itemEnd(l);
+    }), {};
+  });
+}
+const _ = 1e3, j = 100, U = 25;
+class X {
+  windowMs;
+  idleResetMs;
+  missedFrameThresholdMs;
+  #e = [];
+  #t = null;
+  constructor(e = {}) {
+    this.windowMs = e.windowMs ?? _, this.idleResetMs = e.idleResetMs ?? j, this.missedFrameThresholdMs = e.missedFrameThresholdMs ?? U;
+  }
+  add(e, t = performance.now()) {
+    return !Number.isFinite(e) || e <= 0 || !Number.isFinite(t) ? this.snapshot(t) : (this.#t !== null && t - this.#t >= this.idleResetMs && (this.#e.length = 0), this.#t = t, e < this.idleResetMs && this.#e.push({ at: t, duration: e }), this.snapshot(t));
+  }
+  snapshot(e = performance.now()) {
+    this.#r(e);
+    const t = this.#e.map(({ duration: f }) => f);
+    if (t.length === 0)
+      return {
+        samples: 0,
+        fps: 0,
+        average: 0,
+        p95: 0,
+        max: 0,
+        missedFramePercent: 0
+      };
+    const r = [...t].sort((f, i) => f - i), a = t.reduce((f, i) => f + i, 0) / t.length, l = Math.max(0, Math.ceil(r.length * 0.95) - 1), u = t.filter(
+      (f) => f > this.missedFrameThresholdMs
+    ).length;
+    return {
+      samples: t.length,
+      fps: 1e3 / a,
+      average: a,
+      p95: r[l],
+      max: r[r.length - 1],
+      missedFramePercent: u / t.length * 100
+    };
+  }
+  reset() {
+    this.#e.length = 0, this.#t = null;
+  }
+  #r(e) {
+    const t = e - this.windowMs;
+    for (; this.#e.length > 0 && this.#e[0].at < t; )
+      this.#e.shift();
+  }
+}
+function x(s, e) {
+  const { render: t } = s.renderer.info;
+  return {
+    drawCalls: t.drawCalls,
+    frameCalls: t.frameCalls,
+    triangles: t.triangles,
+    points: t.points,
+    lines: t.lines,
+    frameTime: e.average,
+    frameTiming: e
+  };
+}
+function H() {
+  const s = globalThis, e = {
+    viewer: null,
+    canvas: null,
+    domTarget: null,
+    initialized: !1,
+    disposed: !1,
+    ready: !1,
+    lastStatsAt: 0
+  }, t = /* @__PURE__ */ new Map(), r = /* @__PURE__ */ new Set(), a = /* @__PURE__ */ new WeakSet();
+  let l = () => {
+  }, u = () => {
+  };
+  const f = new Promise((n, o) => {
+    l = n, u = o;
+  }), i = (n, o) => {
+    e.disposed && n.type !== "disposed" || s.postMessage(n, o);
+  }, p = (n) => {
+    if (n && typeof n == "object") {
+      if (a.has(n)) return;
+      a.add(n);
+    }
+    i({ type: "error", error: W(n) });
+  }, d = (n, o) => {
+    if (t.has(n))
+      throw new Error(`Worker viewer command already exists: ${n}`);
+    return t.set(n, o), () => {
+      t.get(n) === o && t.delete(n);
+    };
+  }, h = async (n) => {
+    if (e.initialized || e.viewer)
+      throw new Error("The Worker viewer has already initialized.");
+    if (e.disposed) throw new Error("The Worker viewer has been disposed.");
+    if (!s.navigator.gpu)
+      throw new Error("WebGPU is not exposed in this Worker. Use a current Chromium browser or the main-thread Viewer.");
+    B(), e.canvas = n.canvas, e.domTarget = O(n.canvas, n.size);
+    const o = new D({
+      el: e.domTarget,
+      pixelRatio: n.size.pixelRatio,
+      rendererOptions: {
+        canvas: n.canvas,
+        forceWebGL: !1
+      }
+    });
+    e.viewer = o;
+    const m = new X();
+    o.addEventListener("afterRender", ({ delta: w }) => {
+      const g = performance.now(), R = m.add(w * 1e3, g);
+      g - e.lastStatsAt < 250 || (e.lastStatsAt = g, i({ type: "stats", stats: x(o, R) }));
+    }), d("getStats", () => x(o, m.snapshot())), d("getViewpoint", () => o.controls.getCameraViewpoint()), d("setViewpoint", async (w) => {
+      const g = w;
+      return await o.controls.setCameraViewpoint(g.viewpoint, g.enableTransition ?? !0), o.controls.getCameraViewpoint();
+    }), d("render", async () => (await o.render(), x(o, m.snapshot())));
+    const k = {
+      viewer: o,
+      get canvas() {
+        return n.canvas;
+      },
+      status(w) {
+        i({ type: "status", message: w });
+      },
+      emit(w, g) {
+        i({ type: "event", eventType: w, detail: g });
+      },
+      registerCommand: d,
+      onDispose(w) {
+        if (e.disposed) throw new Error("The Worker viewer has been disposed.");
+        return r.add(w), () => r.delete(w);
+      },
+      ready(w) {
+        if (e.disposed) throw new Error("The Worker viewer has been disposed.");
+        if (e.ready) throw new Error("The Worker viewer is already ready.");
+        i({ type: "ready", detail: w }), e.ready = !0;
+      }
+    };
+    if (await o.init(), e.disposed) throw new Error("The Worker viewer was disposed during initialization.");
+    e.initialized = !0, i({ type: "initialized" }), l(k);
+  }, b = (n) => {
+    !e.viewer || !e.domTarget || (I(e.domTarget, n.size), e.viewer.renderer.setPixelRatio(n.size.pixelRatio), e.viewer.onWindowResize());
+  }, S = async (n) => {
+    try {
+      if (!e.initialized) throw new Error("The Worker viewer has not initialized.");
+      const o = t.get(n.command);
+      if (!o) throw new Error(`Unknown Worker viewer command: ${n.command}`);
+      const m = await o(n.payload), k = m instanceof ArrayBuffer ? [m] : Y(m);
+      i({ type: "response", id: n.id, result: m }, k);
+    } catch (o) {
+      i({ type: "response", id: n.id, error: W(o) });
+    }
+  }, L = async () => {
+    if (e.disposed) return;
+    e.disposed = !0;
+    const n = [];
+    for (const o of [...r].reverse())
+      try {
+        await o();
+      } catch (m) {
+        n.push(m);
+      }
+    r.clear();
+    try {
+      e.viewer?.dispose();
+    } catch (o) {
+      n.push(o);
+    }
+    e.viewer = null, e.canvas = null, e.domTarget = null, e.initialized || u(new Error("The Worker viewer was disposed before initialization."));
+    for (const o of n)
+      s.postMessage({ type: "error", error: W(o) });
+    s.postMessage({ type: "disposed" }), s.close();
+  }, T = (n) => {
+    p(n), e.ready || L();
+  };
+  return s.addEventListener("error", (n) => {
+    T(n.error ?? new Error(n.message)), n.preventDefault();
+  }), s.addEventListener("unhandledrejection", (n) => {
+    T(n.reason), n.preventDefault();
+  }), s.addEventListener("message", (n) => {
+    const o = n.data;
+    o.type === "init" ? h(o).catch((m) => {
+      u(m), T(m);
+    }) : o.type === "resize" ? b(o) : o.type === "dom-event" ? e.domTarget && V(e.domTarget, o.event) : o.type === "request" ? S(o) : o.type === "dispose" && L();
+  }), f;
+}
+function Y(s) {
+  const e = /* @__PURE__ */ new Set(), t = /* @__PURE__ */ new WeakSet(), r = (a) => {
+    if (!(!a || typeof a != "object")) {
+      if (a instanceof ArrayBuffer) {
+        e.add(a);
+        return;
+      }
+      if (ArrayBuffer.isView(a)) {
+        a.buffer instanceof ArrayBuffer && e.add(a.buffer);
+        return;
+      }
+      if (!t.has(a)) {
+        if (t.add(a), a instanceof Map) {
+          a.forEach((l, u) => {
+            r(u), r(l);
+          });
+          return;
+        }
+        if (a instanceof Set) {
+          a.forEach(r);
+          return;
+        }
+        Object.values(a).forEach(r);
+      }
+    }
+  };
+  return r(s), [...e];
+}
+export {
+  H as createWorkerViewer,
+  W as serializeError
+};

package/docs/api-batches.md

@@ -0,0 +1,112 @@
+# Batches API
+
+`u-space` 的 `src/batches` 模块提供两种共享渲染聚合层。`ModelInstancedLayer` 面向重复模板的 `InstancedMesh` 渲染；`EditableGeometryBatchLayer` 面向大量普通、主要静态但仍需按对象控制的 Geometry 烘焙合并。两者都从顶层 `u-space` 导出，并使用 `InstanceObject` 作为逻辑对象协议。
+
+```typescript
+import {
+  EditableGeometryBatchLayer,
+  InstanceObject,
+  ModelInstancedLayer,
+  type EditableGeometryBatchOptions,
+  type EditableGeometryBatchStats,
+} from 'u-space';
+```
+
+## 职责边界
+
+| 模块 | 职责 |
+| :--- | :--- |
+| `src/instances` | `InstanceObject` 的身份、transform、样式、bounds、dirty 和 materialize 协议。 |
+| `src/batches` | `InstanceObject` 对应的批量渲染、GPU 状态同步、raycast remap 和资源生命周期。 |
+| 插件/业务 Loader | 模型加载、URL/业务 ID、unsupported fallback 和场景树装配策略。 |
+
+## `ModelInstancedLayer`
+
+`ModelInstancedLayer<T extends InstanceObject>` 继承自 `BaseGroup`。它按模板 key 创建 `InstancedMesh` batch，保留模板中的独立 Mesh 以维持多材质、透明排序和局部包围体，并在实例 dirty 时同步 matrix、颜色、透明度与可见实例集合。
+
+常用方法：
+
+| 方法 | 说明 |
+| :--- | :--- |
+| `reserveBatch(key, template, capacity)` | 为模板预分配实例容量。 |
+| `addInstance(key, template, instance)` / `addInstances(...)` | 添加一个或多个逻辑实例。 |
+| `getInstances()` / `getInstanceById(id)` | 枚举实例或按 `instanceId` 查询。 |
+| `removeInstance()` / `removeInstances()` | 按对象或 ID 删除实例。 |
+| `removeBatch(key)` / `clearBatches()` | 删除一个 batch 或清空全部 batch。 |
+| `setInstanceCulling(options)` | 配置可选的逐实例视锥和屏幕尺寸裁剪。 |
+
+复杂静态模板在射线通过实例包围体后会按需建立 `three-mesh-bvh`；命中会映射回对应 `InstanceObject`。修改实例 transform 时只需操作实例对象；根 Scene 冻结自动矩阵更新时，再调用 `instance.updateWorldMatrix(true, false)` 和 `viewer.invalidate()`。
+
+## `EditableGeometryBatchLayer`
+
+`EditableGeometryBatchLayer<T extends InstanceObject>` 继承自 `BaseGroup`。它把兼容 Mesh 的 transform 烘焙进克隆 Geometry，按材质、Geometry attribute/index 布局、阴影和 `renderOrder` 分组，再通过 `mergeGeometries()` 合并为少量内部 `BaseMesh`。内部 Mesh 是实现细节，不从公共 API 导出。
+
+### 配置与统计
+
+| `EditableGeometryBatchOptions` 字段 | 默认值 | 说明 |
+| :--- | :--- | :--- |
+| `maxVerticesPerBatch` | `1_500_000` | 单个 merged Geometry 的最大顶点数。 |
+| `maxIndicesPerBatch` | `4_500_000` | 单个 merged Geometry 的最大索引数。 |
+| `freezeAnimations` | `false` | 是否允许烘焙带 animation clip/mixer 模板的当前姿态；SkinnedMesh 和 morph target 仍 fallback。 |
+
+`stats` / `build().stats` 包含 `instances`、`sourceMeshes`、`batches`、`drawCallsSaved`、`vertices`、`indices`、`unsupportedInstances` 和 `unsupportedByReason`。
+
+### 创建和构建
+
+```typescript
+import {
+  EditableGeometryBatchLayer,
+  InstanceObject,
+  Model,
+} from 'u-space';
+
+const layer = new EditableGeometryBatchLayer<InstanceObject>({
+  maxVerticesPerBatch: 1_500_000,
+  maxIndicesPerBatch: 4_500_000,
+});
+
+const template = new Model();
+const instances = [new InstanceObject(), new InstanceObject()];
+
+layer.addSource({
+  key: '/models/building.glb',
+  template,
+  instances,
+});
+
+scene.add(layer, ...instances);
+scene.updateMatrixWorld(true);
+
+layer.addEventListener('materialize', ({ instance, object }) => {
+  console.log('materialized', instance.instanceId, object);
+});
+
+const result = layer.build();
+console.table(result.stats);
+```
+
+`addSource()` 接收 `key`、`Model` 模板和同一模板对应的实例数组。全部 source 添加完成后调用一次 `build()`；layer 是 one-shot builder，重复 `build()`、build 后继续 `addSource()` 或 dispose 后复用都会抛出错误。同一个 `InstanceObject` 在一个 layer 中只能出现一次，重复 source 会直接抛错，避免生成无法独立隐藏或拾取的重复烘焙几何。`build()` 返回统计信息，以及没有完全进入 merged Geometry 的 `unsupported` 数组。每个 unsupported 项包含 `key`、fallback `template`、`instances` 和 `reasons`，由调用方决定继续 instancing 还是挂载普通 `Model`。
+
+透明材质、SkinnedMesh、morph target、多材质数组、自定义 NodeMaterial / `onBeforeCompile`、不兼容 Geometry 布局、负行列式变换和未冻结动画会进入 unsupported 路径。负行列式会按实例拆分，正 determinant 的同模板实例仍可合并；`negative-scale` 实例必须使用普通 `Model` fallback，不能继续交给不支持负缩放的 `InstancedMesh`。混合模板仍会合并兼容的不透明子集，并返回只保留不支持子 Mesh 的 fallback 模板。
+
+### 对象状态与 materialize
+
+每个逻辑对象在 Float `DataTexture` 中占一个 RGBA texel。内部 NodeMaterial 通过 TSL 和顶点 `batchObjectIndex` attribute 读取显隐、颜色模式和颜色，因此普通显隐、颜色和不引入半透明的高亮只更新 dirty texel，不重新合并 Geometry。兼容 batch 只包含不透明源材质，并保留源材质原有的 opacity 路径；对象显隐使用独立布尔 `maskNode`，避免动态 opacity 同时参与 alpha 输出和 discard 判断而改变楼壳外观。dirty callback 会立即在 CPU 侧同步对应状态，GPU texture 在下一帧上传；transform materialize 不依赖内部 batch 先通过视锥裁剪，因此从屏幕外移动到屏幕内也不会丢失。
+
+实例 transform 偏离烘焙矩阵或有效 opacity 低于 `0.999` 时，layer 会 clone 完整模板、为本次 materialize 创建独立材质并调用 `InstanceObject.setInstanceRenderObject()`，同时 mask merged Geometry 中的旧副本。新挂载对象会立即提交世界矩阵，冻结根 Scene 时也不会错过当前帧；若另一个 layer materialize 了同一逻辑实例，旧 layer 会通过 dirty callback 隐藏自己的烘焙副本。不同 materialized 实例可以安全使用不同 opacity/highlight，不会反向修改模板或其他实例。业务也可以主动调用 `instance.materialize()`。materialize 成功后 layer 会派发类型化的 `materialize` 事件；如果需要观察 build 期间由初始 opacity 触发的 materialize，应像上例一样在 `build()` 前注册监听：
+
+```typescript
+const model = instances[0].materialize();
+```
+
+`setInstanceMaterializer()` / `clearInstanceMaterializer(materializer?)` 是 batching 实现连接 `InstanceObject` 的低层协议，普通业务不需要直接设置。带 delegate 参数的 clear 只会解除同一个 materializer，避免旧 layer dispose 时清除后来接管实例的新 layer。materialize 是单向操作；恢复原 transform 或 opacity 不会自动重新进入 batch。
+
+### Raycast 与释放
+
+内部 merged Mesh 首次拾取时按需建立 `three-mesh-bvh`，再通过 `faceIndex → vertexIndex → batchObjectIndex` 将命中映射回原始 `InstanceObject`。隐藏 layer 或内部 batch Mesh 会遵循 `ignoreInvisibleWhenRaycast`；已经 materialize 的 state 会从 merged BVH 命中过滤，旧烘焙位置不会残留 ghost picking。
+
+不再使用 layer 时必须调用 `dispose()`。它会取消 dirty 订阅、仅解除仍由当前 layer 持有的 instance materializer、释放状态纹理、Geometry 和克隆材质，并清空内部节点。materialized 普通对象及其独立材质已经交给对应 `InstanceObject`，不由 layer dispose。
+
+## 与 `THREE.BatchedMesh` 的区别
+
+`EditableGeometryBatchLayer` 不是 `THREE.BatchedMesh`。它选择把主要静态 Geometry 真正烘焙合并，并只同步 dirty 对象状态，以减少 draw submission 和逐对象 render-list 工作；代价是展开重复 Geometry、增加 GPU 顶点内存，并在 transform 或半透明变化时 materialize 当前对象。高重复、较大且经常变换的同模板对象通常更适合 `ModelInstancedLayer`。

package/docs/api-effects.md

@@ -5,8 +5,8 @@
 ## `MaterialEffects`
 
 静态工具类，将基于 TSL 的视觉特效直接应用于对象的材质。适用于任何 `Object3D`（支持单个或数组），会自动遍历所有子网格。
-当对象是 `SemanticInstanceObject`（例如 `SceneInstanceObject`、`FacilityInstanceObject` 或楼层里的 `FloorSemanticInstanceObject`）时，`highlightColor()` / `removeHighlightColor()` 会通过 `setSemanticHighlight()` / `clearSemanticHighlight()` 改写该语义实例的颜色和透明度，而不是改动共享 batch 材质。
-`SemanticInstanceObject` 支持 `overwrite` 的替换/染色语义；`depthWrite` 属于共享 batch 材质状态，不能按单个实例设置，因此对该类对象不会生效。
+当对象是 `InstanceObject`（例如 `SceneInstanceObject`、`FacilityInstanceObject` 或楼层里的 `FloorSemanticInstanceObject`）时，`highlightColor()` / `removeHighlightColor()` 会通过 `setInstanceHighlight()` / `clearInstanceHighlight()` 改写该实例的颜色和透明度，而不是改动共享 batch 材质。
+`InstanceObject` 支持 `overwrite` 的替换/染色语义；`depthWrite` 属于共享 batch 材质状态，不能按单个实例设置，因此对该类对象不会生效。
 
 特性：
 - **效果可叠加**：高亮和呼吸效果可同时作用于同一对象，呼吸在高亮结果之上混合

package/docs/api-interactions.md

@@ -4,6 +4,14 @@
 
 `InteractionManager` 在 `Viewer` 内部自动实例化，可通过 `viewer.interactionManager` 访问。
 
+对于三角形较多的静态模型，可以在模型加载后调用 `enableMeshBVHRaycast(root)`。该函数不会修改 Three.js 原型；它先保留每个 Mesh 的局部包围体粗筛，只有射线命中包围球后才为至少 10000 个三角形的 geometry 按需建立并复用 `three-mesh-bvh`。小几何、蒙皮、morph target 或自定义 raycast 对象会继续使用原始路径。
+
+```ts
+import { enableMeshBVHRaycast } from 'u-space';
+
+enableMeshBVHRaycast(loadedModel);
+```
+
 ## 启用交互事件
 
 出于性能考虑，指针移动事件默认处于禁用状态。如需悬停和拖拽效果，必须显式开启。

package/docs/api-managers.md

@@ -129,7 +129,7 @@ viewer.objectManager.showAll();
 
 #### `setOpacity(id: string, opacity: number)`
 
-设置指定对象所有材质的透明度。对于 `SemanticInstanceObject`（例如 `SceneInstanceObject`、`FacilityInstanceObject` 或 `FloorSemanticInstanceObject`），会调用 `setSemanticOpacity()` 写入该实例的透明度，而不会影响同一模型 path 或同一楼层内的其他实例。
+设置指定对象所有材质的透明度。对于 `InstanceObject`（例如 `SceneInstanceObject`、`FacilityInstanceObject` 或 `FloorSemanticInstanceObject`），会调用 `setInstanceOpacity()` 写入该实例的透明度，而不会影响同一模型 path 或同一楼层内的其他实例。
 
 ```typescript
 viewer.objectManager.setOpacity('building-01', 0.3);