soonspacejs 2.16.8 → 2.16.10

package/README.md

@@ -12,3 +12,45 @@
 `@robotlegsjs/signals` 是 SDK 的运行依赖，通过 npm 或 pnpm 安装 SoonSpace 时会自动安装，无需单独添加。
 
 SDK 构建将 signals 保留为外部导入。Vite、Webpack 等构建工具会解析该依赖；直接在浏览器中使用原生 ES modules 时，需要在 import map 中配置 `@robotlegsjs/signals` 对应的 ESM 地址。
+
+## 统一资源请求头
+
+从 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:` 资源不添加全局默认头；缓存命中没有网络请求，本功能不改变模型缓存策略。