@microi.net/cli 5.9.2 → 5.9.4

package/skills/unity-integration/references/webgl-hosting.md

@@ -1,57 +1,57 @@
-# WebGL 宿主、性能与部署
-
-## Poster-first 生命周期
-
-1. 首屏只加载 DOM、主视觉和轻量构建状态。
-2. 用户点击“进入 3D”后才创建 iframe/Canvas 并下载 Loader、Data、WASM。
-3. 加载中显示真实进度，不用无限假动画。
-4. 页面不可见或离开视口时 `SendMessage(..., SetHostPaused, true)`。
-5. 重回前台恢复；离开页面调用 `Quit()` 并移除全部监听与全局回调。
-
-错误状态至少区分：构建缺失、Loader 下载失败、Unity 初始化失败、浏览器能力不足、网络/CORS 失败。错误页仍应保留重试、返回与文档入口。
-
-## 上下文注入
-
-宿主在 Unity ready 后调用：
-
-```js
-unityInstance.SendMessage('MicroiApiClient', 'ApplyMicroiHostContext', JSON.stringify({
-  ApiBaseUrl: runtime.apiBase,
-  OsClient: runtime.osClient,
-  Authorization: runtime.token,
-  Did: runtime.did
-}))
-```
-
-- 不使用 `?token=`、`?osClient=` 或 `?apiBase=` 传会话。
-- iframe 同源时可读取父窗口内存上下文；跨域时由父页面显式 SendMessage，不能放宽为 `postMessage('*')` 接收秘密。
-- 若使用 `postMessage`，发送与接收双方都校验精确 Origin、消息类型和结构。
-
-## Token 轮换
-
-Unity 发送 `(newToken, requestToken)`。宿主只在当前 Token 仍等于 `requestToken`（或统一认证库明确允许）时覆盖，防止先发请求后到达的旧响应回滚新会话。
-
-更新顺序：统一认证库 → 微应用宿主 → 当前内存上下文 → 再注入 Unity。任何日志和业务事件都不得携带 Token。
-
-## 性能分档
-
-- 桌面 DPR 上限通常不超过 2；移动实验档建议 1.0–1.25。
-- 阴影距离、级联、粒子、后处理、LOD 与贴图分辨率按设备档位联动。
-- 首次下载和解压峰值要纳入浏览器内存；不能只看压缩包大小。
-- 大型孪生数据按区域/层级流式加载，避免把全部模型放入一个 Data 包。
-- 尊重 `prefers-reduced-motion`；DOM 外壳禁用非必要动效，Unity 内按项目需求提供镜头/粒子降级。
-
-## 静态服务器
-
-常见文件类型：
-
-| 文件 | MIME |
-|---|---|
-| `.wasm` | `application/wasm` |
-| `.js` | `application/javascript` |
-| `.data` | `application/octet-stream` |
-| `.json` | `application/json` |
-
-预压缩 `.gz/.br` 必须返回匹配的 `Content-Encoding`，不能只靠扩展名。若托管方不能配置响应头，构建时启用 Unity 解压回退，并实测性能。
-
-正式验收使用 HTTP(S)，检查状态码、MIME、Content-Encoding、CORS、缓存、Service Worker、控制台错误、全屏和退出后的内存/GPU 回落。
+# WebGL 宿主、性能与部署
+
+## Poster-first 生命周期
+
+1. 首屏只加载 DOM、主视觉和轻量构建状态。
+2. 用户点击“进入 3D”后才创建 iframe/Canvas 并下载 Loader、Data、WASM。
+3. 加载中显示真实进度，不用无限假动画。
+4. 页面不可见或离开视口时 `SendMessage(..., SetHostPaused, true)`。
+5. 重回前台恢复；离开页面调用 `Quit()` 并移除全部监听与全局回调。
+
+错误状态至少区分：构建缺失、Loader 下载失败、Unity 初始化失败、浏览器能力不足、网络/CORS 失败。错误页仍应保留重试、返回与文档入口。
+
+## 上下文注入
+
+宿主在 Unity ready 后调用：
+
+```js
+unityInstance.SendMessage('MicroiApiClient', 'ApplyMicroiHostContext', JSON.stringify({
+  ApiBaseUrl: runtime.apiBase,
+  OsClient: runtime.osClient,
+  Authorization: runtime.token,
+  Did: runtime.did
+}))
+```
+
+- 不使用 `?token=`、`?osClient=` 或 `?apiBase=` 传会话。
+- iframe 同源时可读取父窗口内存上下文；跨域时由父页面显式 SendMessage，不能放宽为 `postMessage('*')` 接收秘密。
+- 若使用 `postMessage`，发送与接收双方都校验精确 Origin、消息类型和结构。
+
+## Token 轮换
+
+Unity 发送 `(newToken, requestToken)`。宿主只在当前 Token 仍等于 `requestToken`（或统一认证库明确允许）时覆盖，防止先发请求后到达的旧响应回滚新会话。
+
+更新顺序：统一认证库 → 微应用宿主 → 当前内存上下文 → 再注入 Unity。任何日志和业务事件都不得携带 Token。
+
+## 性能分档
+
+- 桌面 DPR 上限通常不超过 2；移动实验档建议 1.0–1.25。
+- 阴影距离、级联、粒子、后处理、LOD 与贴图分辨率按设备档位联动。
+- 首次下载和解压峰值要纳入浏览器内存；不能只看压缩包大小。
+- 大型孪生数据按区域/层级流式加载，避免把全部模型放入一个 Data 包。
+- 尊重 `prefers-reduced-motion`；DOM 外壳禁用非必要动效，Unity 内按项目需求提供镜头/粒子降级。
+
+## 静态服务器
+
+常见文件类型：
+
+| 文件 | MIME |
+|---|---|
+| `.wasm` | `application/wasm` |
+| `.js` | `application/javascript` |
+| `.data` | `application/octet-stream` |
+| `.json` | `application/json` |
+
+预压缩 `.gz/.br` 必须返回匹配的 `Content-Encoding`，不能只靠扩展名。若托管方不能配置响应头，构建时启用 Unity 解压回退，并实测性能。
+
+正式验收使用 HTTP(S)，检查状态码、MIME、Content-Encoding、CORS、缓存、Service Worker、控制台错误、全屏和退出后的内存/GPU 回落。