soonspacejs 3.0.0-alpha.1 → 3.0.0-alpha.10

package/README.md

@@ -12,3 +12,63 @@
 `@robotlegsjs/signals` 是 SDK 的运行依赖，通过 npm 或 pnpm 安装 SoonSpace 时会自动安装，无需单独添加。
 
 SDK 构建将 signals 保留为外部导入。Vite、Webpack 等构建工具会解析该依赖；直接在浏览器中使用原生 ES modules 时，需要在 import map 中配置 `@robotlegsjs/signals` 对应的 ESM 地址。
+
+## 场景 Info 统计
+
+开启 `showInfo` 后，左下角 `meshes` 统计每个 Entity 的原始 Mesh 部件及原生 Mesh，不统计生成的合批对象、线段部件或选中覆盖层；切换合批不会改变原始 Mesh 数。
+
+`objects` 是实际渲染树节点数；`vertices` 和 `triangles` 按有效几何、实例数及 drawRange 统计，不含 BatchedMesh 预留容量，也不是当前帧经过视锥裁剪或多 pass 后的提交量。仅有 GPU 索引缓冲而没有 CPU 索引数据时，顶点数沿用声明的顶点范围，不进行同步 GPU 回读。
+
+统计随结构、几何和 Entity 提交变更缓存更新，静止重绘及相机运动不会为 Info 全量遍历场景。直接修改原生几何或实例数量后，应发送 `ssp.signals.geometryChanged`；共享几何的通知会同时更新其所有使用者。
+
+## Entity 贴图预上传
+
+`ssp.models.load()` 在返回模型资源前，分帧准备新解码 glTF 的静态贴图。CPS 的 `loadEntityScene()` 通过同一条核心加载路径获得这项优化，不需要插件或业务层另建队列。
+
+队列由当前 SoonSpace 实例管理，共享贴图按版本去重，每轮以 4 ms 为软预算。单张贴图上传不能中断，仍可能超过预算；这项优化减少首次绘制集中上传的长帧，不保证整体加载更快或达到 60 FPS。没有待处理任务时，不保留帧回调或定时器，也不会每帧全量遍历模型。
+
+取消请求只移除该请求的排队任务，保留其他请求仍在使用的共享贴图。销毁 SoonSpace 会清理队列和监听器；WebGL 上下文丢失时暂停，恢复后重新准备尚未完成模型的贴图。rAF 暂停时有定时调度兜底，但浏览器仍可能对后台页面限速。
+
+原生 `loadModel()` 保留首次绘制时上传的行为，避免改变 `onLoad` 中初始化贴图的时序。同步 `models.register()`、视频、深度、渲染目标和带自定义 `onUpdate` 的贴图不参与预上传；预上传失败时沿用原生绘制路径，不因这项优化拒绝模型加载。
+
+## 统一资源请求头
+
+从 2.16.9 起，在创建实例或开始加载资源前配置全局默认请求头：
+
+```ts
+import SoonSpace, { RequestHeaders } from 'soonspacejs'
+
+Object.assign(RequestHeaders, {
+  Authorization: `Bearer ${token}`,
+  'Company-Id': companyId,
+  'Project-Id': projectId,
+})
+
+const ssp = new SoonSpace(options)
+await ssp.loadModel({ id: 'model', url: modelUrl })
+```
+
+`RequestHeaders` 和旧名称 `FileRequestHeaders` 指向同一个对象，旧代码可继续使用。更新或删除属性会影响后续实际发起的请求；不要替换该对象。切换上下文时应同步删除已不再适用的企业、项目等字段。
+
+```ts
+RequestHeaders.Authorization = `Bearer ${newToken}`
+delete RequestHeaders['Project-Id']
+
+// 退出登录时移除默认凭证。
+delete RequestHeaders.Authorization
+delete RequestHeaders['Company-Id']
+```
+
+默认头应用于 SDK 主库与插件可控制的 HTTP(S) 资源请求，包括模型主文件、模型依赖、图片、工程清单及解码器资源。具体请求或插件显式设置的同名头优先，名称大小写不敏感。默认头也会应用于 SDK 加载的跨源资源；浏览器仍要求相应服务允许 CORS。SDK 不会自动读取业务登录凭证。
+
+KTX2 在配置请求头时需要明确的解码器路径，沿用现有配置方法：
+
+```ts
+ssp.setModelKtx2DecoderPath('/libs/basis/')
+```
+
+没有请求头或解码器已初始化时保留 Three.js 原行为；配置请求头且未提供路径时，会在联网前提示补充路径，不会猜测上游模块的默认地址。
+
+IFC 在配置资源请求头时使用现有单线程 WASM 实现，确保 WASM 下载也经过带头传输，避免原生 pthread Worker 请求无法设置 Header。无请求头时保留原有自动线程选择；宿主显式提供的 Worker 协议不变。
+
+此配置不修改宿主页面自己的 fetch/XHR，也不接管原生视频播放、宿主已设置 src 的 DOM 元素或宿主创建的 Worker。`data:`、`blob:` 资源不添加全局默认头；缓存命中没有网络请求，本功能不改变模型缓存策略。