soonspacejs 3.0.0-alpha.8 → 3.0.0-alpha.9

package/README.md

@@ -30,3 +30,45 @@ SDK 构建将 signals 保留为外部导入。Vite、Webpack 等构建工具会
 取消请求只移除该请求的排队任务，保留其他请求仍在使用的共享贴图。销毁 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:` 资源不添加全局默认头；缓存命中没有网络请求，本功能不改变模型缓存策略。