# SoonSpace

![logo](https://www.xwbuilders.com/soonspacejs/logo/logo_all.svg)

- 文档：[https://www.xwbuilders.com/soonspacejs/](https://www.xwbuilders.com/soonspacejs/)
- 样例：[https://www.xwbuilders.com/soonspacejs/examples/](https://www.xwbuilders.com/soonspacejs/examples/)
- GitHub: [https://github.com/soonspacejs](https://github.com/soonspacejs)
- npm: [https://www.npmjs.com/package/soonspacejs](https://www.npmjs.com/package/soonspacejs)

## Signals 依赖

`@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:` 资源不添加全局默认头；缓存命中没有网络请求，本功能不改变模型缓存策略。