@nebula-spatial/viewer 0.3.0 → 0.4.0

package/README.md

@@ -1,220 +1,595 @@
-# @nebula-spatial/viewer
-
-浏览器侧只读 Three.js Viewer Facade。负责场景运行时、相机、输入、拾取、渲染循环和
-资源释放；`viewer.cad` 提供与 `@nebula-spatial/cad-loader` 集成的 CAD 文档能力。
-
-Viewer 不解析 DXF/DWG，也不提供编辑命令、历史记录或业务状态管理。
-
-## 插件与 Headless 模式
-
-Viewer 的扩展首选插件化：插件通过受限的 `ViewerPluginContext` 读取不可变快照、调用
-commands、订阅事件并注册贡献点，不能访问内部 scene、renderer 或 camera。
-
-```ts
-let stop: (() => void) | undefined;
-const annotationPlugin = {
-  id: 'annotation',
-  activate(ctx) {
-    stop = ctx.events.on('camera-change', () => updateAnnotations(ctx.cad.$read()));
-    ctx.contribute({
-      kind: 'command',
-      id: 'annotation.refresh',
-      handler: () => updateAnnotations(ctx.cad.$read()),
-    });
-  },
-  deactivate() { stop?.(); /* 清理业务资源 */ },
-};
-
-const viewer = createViewer({ viewport, canvas, cadInteraction: 'manual' });
-viewer.use([annotationPlugin]);
+# @nebula-spatial/viewer
+
+浏览器侧只读 Three.js 统一资产 Viewer Facade。负责场景运行时、相机、输入、拾取、渲染循环和
+资源释放；`openAsset()` 统一加载 CAD、GLB/glTF、URDF、MJCF 与 USD，`viewer.cad` 保留与
+`@nebula-spatial/cad-loader` 集成的兼容能力。
+
+Viewer 不解析 DXF/DWG，也不提供编辑命令、历史记录或业务状态管理。
+
+## 插件与 Headless 模式
+
+Viewer 的扩展首选插件化：插件通过受限的 `ViewerPluginContext` 读取不可变快照、调用
+commands、订阅事件并注册贡献点，不能访问内部 scene、renderer 或 camera。
+
+```ts
+let stop: (() => void) | undefined;
+const annotationPlugin = {
+  id: 'annotation',
+  activate(ctx) {
+    stop = ctx.events.on('camera-change', () => updateAnnotations(ctx.cad.$read()));
+    ctx.contribute({
+      kind: 'command',
+      id: 'annotation.refresh',
+      handler: () => updateAnnotations(ctx.cad.$read()),
+    });
+  },
+  deactivate() { stop?.(); /* 清理业务资源 */ },
+};
+
+const viewer = createViewer({ viewport, canvas, cadInteraction: 'manual' });
+viewer.use([annotationPlugin]);
+```
+
+`viewer.use()` 会立即激活插件；`viewer.dispose()` 按注册逆序停用插件并回收插件注册的
+事件、贡献点和 DOM。重复的插件或贡献点 id 会被拒绝。
+
+### 插件生命周期
+
+```ts
+interface ViewerPlugin {
+  id: string;
+  activate(context: ViewerPluginContext): void | Promise<void>;
+  deactivate?(): void | Promise<void>;
+}
+```
+
+- `activate`：`viewer.use([...])` 调用时立即执行；可以在里面注册事件、贡献点、布局挂载。
+  若返回 Promise，异步失败会被捕获并回滚该插件（不会波及后来用同 id 注册的替换插件）。
+- `deactivate`：`viewer.dispose()` 或 `use(..., { replace: true })` 换掉插件时调用。Viewer
+  已自动回收它注册的事件、贡献点和 DOM，这里只清理**插件自己的**业务资源（定时器、外部
+  请求、业务状态）。async 失败只记录，不抛出。
+- 同一个 `id` 只能注册一次；一个插件内的贡献点 `id` 也必须全局唯一（`command` 类按
+  `command.id` 在 `viewer.commands` 里注册）。
+
+### `ViewerPluginContext` 的 API
+
+插件在 `activate` 拿到的 `context` 是受限的宿主句柄，能力分四块，且**只能读、只能通过
+commands 写**，不能直接改 `viewer.cad.layers.rows[0].visible` 这类可变模型。
+
+**读状态（返回不可变快照，不是活模型）**
+
+```ts
+ctx.cad.$read(): CadViewerSnapshot               // 深冻结 CAD 状态快照
+ctx.asset.$read(): AssetPreviewSnapshot | null    // 活动资产；无资产为 null
+ctx.asset.$readControl(): AssetControlState       // 按钮 pressed 的权威状态
+ctx.viewer.$getState(): ViewerState  // { viewMode, selectedObject, highlightedObject, isDisposed }
+```
+
+快照每次调用都是新的深冻结对象，可直接用于 React `useSyncExternalStore` / Vue `ref`。
+
+**写状态（命令，经过内核保证不变量）**
+
+```ts
+ctx.commands.setLayerVisible(index, visible): boolean  // 确定性设置，返回是否真的改变了
+ctx.commands.setSelection(selection: CadSelection | null): void
+ctx.commands.fitDocument(): boolean
+ctx.commands.setViewMode(mode): void
+ctx.commands.play()/pause()/reset(): boolean
+ctx.commands.fitView(): boolean
+ctx.commands.setUpAxis('y' | 'z'): boolean
+ctx.commands.setGroundVisible(visible): boolean
+ctx.commands.setCollisionVisible(visible): boolean
+ctx.commands.setTheme('dark' | 'light'): boolean
+```
+
+这些命令经过 active epoch、ready phase 与 capability 门控。插件命令失败返回 `false`；成功控制变化统一发布 `asset-control-change`，插件不要保存自己的 pressed truth。
+
+**订阅事件**
+
+```ts
+ctx.events.on(type, listener): () => void   // 返回退订函数；插件停用时自动退订
+```
+
+`type` 是 `ViewerEventMap` 和 `CadViewerEventMap` 的并集（`camera-change`、
+`document-change`、`layer-change`、`inspector-change`、`hud-change`、`load-progress`、
+`error` 等，按事件源自动路由到 viewer 或 cad）。事件载荷始终带最新状态快照或最小
+payload，业务不要假设事件里能拿到活模型。
+
+**布局挂载**
+
+```ts
+ctx.layout.mount(node, options?: { position?: 'left' | 'right' | 'top' | 'bottom' | 'overlay' }): Disposable
+ctx.layout.onInsetsChange(listener: (insets) => void): () => void
+```
+
+`mount` 把插件自己的 DOM 挂进 viewer 的布局宿主，返回的 `Disposable.dispose()` 或插件停用
+时移除该节点。`position` 是建议的默认归属，`overlay` 是默认值（不参与视口 inset 计算）。
+`onInsetsChange` 订阅 `ui-layout-change` 的 `contentInsets`，让插件在面板开合时自己排布、
+Viewer 会在 inset 变化时自行 resize——这是"逃逸通道"，业务不需要请求内核新增一个上下面板贡献点，
+用 `mount` + `onInsetsChange` 就能实现任意方位布局。
+
+### 注册贡献点（`ctx.contribute`）
+
+贡献点定义"插件能往 Viewer 里注入什么"，目前共 8 类。`contribute` 返回 `Disposable`，
+`dispose()` 或插件停用时会自动注销对应贡献点并清理其 DOM/订阅。
+
+| kind | 作用 | 关键字段 |
+|---|---|---|
+| `panel` | 挂一个常驻面板 | `factory(ctx) => Node` |
+| `toolbar` | 往工具栏加按钮 | `items: ToolbarItem[]` |
+| `hud` | 悬浮层内容 | `factory(ctx) => Node` |
+| `statusbar` | 状态栏条目 | `factory(ctx) => Node` |
+| `inspector` | 选中对象的属性渲染（多分派） | `matcher(sel) => boolean` + `render(ctx, sel) => Node` |
+| `interaction` | 拦截拾取/选择/hover 管线 | `hooks: { onPick?, onHover?, onSelect?, onClear? }` |
+| `command` | 注册可执行命令（可绑快捷键） | `handler(ctx, args?) => void` |
+| `fit-policy` | 定制 `fitView()` 的范围解析 | `resolve(ctx) => Box3 \| null` |
+
+**`factory` 的定义**（panel/hud/statusbar 类贡献点）：
+
+```ts
+factory: (ctx: ViewerPluginContext) => Node
+```
+
+- 它是一个**惰性渲染钩子**：不是注册时执行，而是 Viewer 真正把这个贡献点挂进布局 DOM 时
+  才调用一次。注册一个 panel 贡献点不会立刻渲染，`viewer.use()` 激活插件 + 该面板进入
+  布局后才会调用。
+- **只调一次**。返回一个真实的 DOM `Node`（`Element` 或 `Fragment`），Viewer 会包进一个
+  带 `data-viewer-contribution` / `data-viewer-contribution-id` 标记的容器并加进宿主。
+  返回非 `Node` 会抛错（`factory` 必须返回 Node，不是 string / 异步 / VNode）。
+- 它拿到和 `activate` 同一个受限 `context`，所以可以在挂载时把 `ctx.cad.$read()`、
+  `ctx.events` 绑定进返回的 Node 里，让面板内部自行响应状态变化——因为 `factory` 本身
+  **不负责每次状态变化时重建 DOM**，响应逻辑要在 Node 内部（一个 Vue 组件、一段自己订阅
+  `ctx.events` 的逻辑）完成。
+- 贡献点 `dispose()` 或插件停用时，容器连同里面的 Node 一起被移除；`factory` 内创建的业务
+  资源由你在 `deactivate` 里清理。
+
+**与 `inspector` 的 `render` 的区别**（这是最易混的，两者都返回 Node，但时机不同）：
+
+| 钩子 | 调用时机 | 次数 | 职责 |
+|---|---|---|---|
+| `factory`（panel/hud/statusbar） | 贡献点挂载进布局时 | 一次性 | 常驻面板的初始 DOM 结构 |
+| `render`（inspector） | 每次 `inspector-change` | 每次选中变化 | 按当前选中项重建属性详情 |
+
+`panel` 的 `factory` 建一次"固定壳子"，内容由内部订阅事件自己更新；`inspector` 的 `render`
+随 selection 变化反复调用，因为属性面板内容由"当前选中的对象"决定。
+
+**inspector 分派**：内核按 `CadSelection.kind`（`insert`/`text`）分派，多个 `inspector`
+贡献点用 `matcher` 竞争，注册顺序在前者优先（可用 `id` 去重或控制优先级），命中的那个
+`render`。它是"只读 context 渲染"，不改任何状态。
+
+**interaction 钩子**（行为类，需受控）：
+
+```ts
+hooks: {
+  onPick(hit: CadHit | null): boolean | void,  // 返回 false = 消费这次点击，截断内核管线
+  onHover(hit: CadHit | null): void,
+  onSelect(selection: CadSelection | null): void,
+  onClear(): void,
+}
+```
+
+`onPick` 返回 `false` 时，Viewer 不再执行它默认的选择/拾取——这是插件"接管点击"的入口
+（比如标注模式）。`managed` 模式下内置交互管线先走插件 hook，再落到 Viewer 默认行为；
+`manual` 模式下 Viewer 不做默认行为，只把事件交给插件，插件自己调 `hitTest`/`select`/`overlays`。
+`onSelect`/`onClear` 在 inspector 选择变化/清空时触发。
+
+**fit-policy**：`viewer.fitView()` 无参调用时，先询问所有 `fit-policy` 贡献点的 `resolve`，
+返回非 `null` 的第一个作为适配范围；都不返回则回退到混合内容范围。适合"自定义某个来源的
+适配边界"这类需求。
+
+### 与 `cadInteraction` 的关系
+
+CAD 点击策略由 `cadInteraction` 统一表达：`managed`（默认）由 Viewer 完成拾取和选择，
+`manual` 只提供 `viewer.cad.hitTest/select/clearSelection` 原语，`disabled` 关闭 CAD 点击语义
+只保留导航。`cad-readonly` UI 仅在 `managed` 模式下挂载。
+
+- `managed`：插件 `interaction` hook 在最前面拦截，hook 不消费时走 Viewer 默认选择。
+- `manual`：Viewer 不做选择，插件完全接管——用 `hitTest` 自己决定点到了什么，再调
+  `select` / `clearSelection` / `overlays`。
+- `disabled`：Viewer 不做 CAD 语义拾取，交互 hook 的 `onPick`/`onHover` 不再派发，
+  插件不该假设会收到点击。
+
+`viewer.overlays.set/remove` 是手动模式的受控 overlay 原语；传入的 `Object3D` 默认由业务
+拥有，只有显式传 `{ owned: true }` 时 Viewer 才在移除时负责释放。
+
+`openAsset()` 是 CAD、3D 模型和仿真资产的统一打开入口。CAD asset 的 `ready` 在头部解析完成时
+resolve；增量几何和 sidecar 仍通过 `load-progress`、`document-change` 与 `hud-change` 继续报告。
+替换中的 open 会以 `E_SUPERSEDED` 结束，外部 `AbortSignal` 取消会以 `E_ABORTED` 结束。
+旧的 `viewer.cad.open()` 仅作为兼容入口保留，已标记为 deprecated。
+
+`viewer.cad.getSnapshot()` 返回深冻结快照（包括独立的 `CadInspectorSnapshot` / `CadHudSnapshot` 数据形状），适合状态管理；图层可用
+`layers.setVisible(index, visible)` / `setVisibleBatch()` 做确定性更新。无参
+`viewer.fitView()` 与 `viewer.fitAll()` 适配全部内容，`viewer.cad.fitSelection()` 只适配当前
+CAD 选择。
+
+高层相机状态通过 `viewer.camera.getState()`、`setState()` 和 `reset()` 访问，不暴露底层
+Three.js Camera。应用成功后会同步发布 `camera-change` 和 `viewport-change`；跨 2D/3D 时还会
+发布 `view-mode-change`。`camera-change.reason` 区分 `pointer`、`wheel`、`fit`、`restore`、
+`api` 和 `view-mode`。当前 `setState()` 立即应用快照，动画切换属于后续能力。
+
+## 统一资产入口
+
+```ts
+const preview = viewer.openAsset('/models/robot.glb', { format: 'auto' });
+const stop = preview.subscribe((snapshot) => updateLoadingUi(snapshot));
+await preview.ready;
+await preview.close();
+stop();
+```
+
+`openAsset()` 同步返回句柄；首次 snapshot 固定为 `detecting`。Viewer 同时只保留一个活动资产，
+旧句柄的 `close()` 只等待自己的资源清理，不会关闭后来打开的资产。`closeAsset()` 关闭调用瞬间
+的活动资产。普通模型以 borrowed 方式挂入唯一 scene runtime，GPU 资源只由模型 session 释放。
+
+GLB/glTF 文件没有权威的 up 轴声明（规范 Y-up，CAD 导出常为 Z-up）。预览世界固定 Z-up；
+对轴向错误的模型传 `upAxis: 'y'` 打开（仅旋转资产根节点，不移动相机与世界），或运行期用
+`preview.setUpAxis('y' | 'z')` / `preview.getUpAxis()` 切换（切换后自动重铺地面并重新适配
+相机，不平移贴地）。能力标志为 `capabilities.canReorientUpAxis`。仿真资产的格式自带 up 轴，
+不提供该能力。
+
+地面（网格线 + 反射 + 接影地板）可通过 `preview.setGroundVisible(false)` 整体隐藏、`preview.getGroundVisible()`
+查询，对应 `capabilities.canToggleGround`；模型与仿真预览均支持。隐藏时跳过反射 pass，接影地板与地面阴影一并隐藏。
+
+GLB/glTF 的 Draco decoder 路径由宿主显式配置，不使用站点根路径默认值：
+
+```ts
+const viewer = createViewer({
+  viewport,
+  canvas,
+  assets: { dracoDecoderPath: new URL('./draco/', document.baseURI).href },
+});
+```
+
+URDF 和 MJCF 以 MuJoCo WASM 运行，仍由 Viewer 唯一的 scene/runtime/RAF 驱动。多文件模型请传
+`{ kind: 'files', files, entry }`；`entry` 是包内 URDF 或 MJCF XML 路径。USD 会加载视觉与可可靠映射的物理数据，远端 URL 会以根 USD 文件的完整 URL 作为相对子层、纹理和其他资源的解析基址。
+当前明确支持动态刚体以及树形拓扑的 `PhysicsFixedJoint`、`PhysicsRevoluteJoint`、`PhysicsPrismaticJoint`，包括局部锚点、轴向、有限/无限限位、零宽锁定限位和 force drive；这些资产会启用 play/pause/reset、碰撞代理和拖拽施力。闭环/多父关节、其他关节类型或无法保持物理语义的属性不会被静默编译成错误仿真：当 OpenUSD 已经成功构建完整视觉场景、且失败属于 Viewer 明确识别的 USD 到 MuJoCo 物理语义缺口时，会显式降级为仅视觉预览，禁用播放、复位、碰撞代理和拖拽，并在场景顶部展示降级原因；网络请求、USD/视觉解析、安全上下文、单位校验、取消操作、MuJoCo 初始化及未知错误仍按加载失败处理。没有刚体的 USD 仍作为正常的静态视觉资产预览，不显示降级警告。
+
+```ts
+const preview = viewer.openAsset({
+  kind: 'files',
+  entry: 'robot/scene.xml',
+  files: selectedFiles.map((file) => ({ path: file.webkitRelativePath || file.name, file })),
+}, { format: 'mjcf' });
+await preview.ready;
+preview.pause();
+preview.reset();
+preview.play();
+```
+
+### 远端仿真资产与格式识别边界
+
+省略 `format` 与 `format: 'auto'` 等价：只按明确扩展名或已注册 loader 的明确 `match()` 结果识别。
+通用 `.xml`、无扩展名 URL、目录 URL 不会自动猜测为 MJCF、URDF 或 CAD；无法识别时显示
+“不支持的资产格式”，调用方应指定 `format`。格式识别成功不代表文件内容或全部仿真语义一定受支持；
+读取、解析、依赖资源或运行时初始化失败显示“资产加载失败”。
+
+远端单文件应传实际入口文件 URL，而不是目录 URL，例如：
+
+```ts
+const preview = viewer.openAsset('https://cdn.example.com/robot/scene.xml', {
+  format: 'mjcf',
+  baseUrl: 'https://cdn.example.com/robot/',
+});
+await preview.ready;
+```
+
+Viewer 不枚举 CDN 目录。远端目录型资产应传实际入口文件 URL，保持服务器上的相对目录结构；
+需要签名 URL、私有鉴权或路径重写时，通过 `resourceResolver` 映射入口文件引用的子资源：
+
+```ts
+const preview = viewer.openAsset('https://cdn.example.com/robot/scene.xml', {
+  format: 'mjcf',
+  baseUrl: 'https://cdn.example.com/robot/',
+  resourceResolver: {
+    async resolve(path, { signal } = {}) {
+      return getAuthorizedAssetUrl(path, { signal });
+    },
+  },
+});
+await preview.ready;
 ```
 
-`viewer.use()` 会立即激活插件；`viewer.dispose()` 按注册逆序停用插件并回收插件注册的
-事件、贡献点和 DOM。重复的插件或贡献点 id 会被拒绝。
-
-CAD 点击策略由 `cadInteraction` 统一表达：`managed`（默认）由 Viewer 完成拾取和选择，
-`manual` 只提供 `viewer.cad.hitTest/select/clearSelection` 原语，`disabled` 关闭 CAD 点击语义
-只保留导航。`cad-readonly` UI 仅在 `managed` 模式下挂载。
-
-`viewer.overlays.set/remove` 是手动模式的受控 overlay 原语；传入的 `Object3D` 默认由业务
-拥有，只有显式传 `{ owned: true }` 时 Viewer 才在移除时负责释放。
-
-`viewer.cad.open()` 在头部解析完成时 resolve；增量几何和 sidecar 仍通过
-`load-progress`、`document-change` 与 `hud-change` 继续报告。替换中的 open 会以
-`E_SUPERSEDED` 结束，外部 `AbortSignal` 取消会以 `E_ABORTED` 结束。
-
-`viewer.cad.getSnapshot()` 返回深冻结快照（包括独立的 `CadInspectorSnapshot` / `CadHudSnapshot` 数据形状），适合状态管理；图层可用
-`layers.setVisible(index, visible)` / `setVisibleBatch()` 做确定性更新。无参
-`viewer.fitView()` 与 `viewer.fitAll()` 适配全部内容，`viewer.cad.fitSelection()` 只适配当前
-CAD 选择。
-
-高层相机状态通过 `viewer.camera.getState()`、`setState()` 和 `reset()` 访问，不暴露底层
-Three.js Camera。应用成功后会同步发布 `camera-change` 和 `viewport-change`；跨 2D/3D 时还会
-发布 `view-mode-change`。`camera-change.reason` 区分 `pointer`、`wheel`、`fit`、`restore`、
-`api` 和 `view-mode`。当前 `setState()` 立即应用快照，动画切换属于后续能力。
-
-## CAD 快速开始
-
-```ts
-import { createViewer } from '@nebula-spatial/viewer';
-
-const viewer = createViewer({
-  viewport: document.querySelector<HTMLElement>('#viewport')!,
-  canvas: document.querySelector<HTMLCanvasElement>('#viewport canvas')!,
-  initialViewMode: '2d',
-});
-
-viewer.cad.on('document-change', ({ document }) => {
-  updateDocumentTitle(document?.filename ?? '');
-});
-
-await viewer.cad.open('/api/files/demo/result', {
-  documentKey: 'demo',
-  filename: 'demo.dxf',
-});
-
-viewer.dispose();
-```
-
-Viewer 默认使用 Three.js 内置 `RoomEnvironment` 提供基于图像的环境光，不会替换场景背景。
-外部系统也可以传入自己的等距柱状 HDR URL：
-
-```ts
-const viewer = createViewer({
-  viewport,
-  canvas,
-  environment: {
-    type: 'hdr',
-    url: 'https://static.example.com/environments/studio.hdr',
-  },
-});
-```
-
-HDR 资源由浏览器直接请求，因此资源服务器需要允许当前应用域名进行 CORS 访问。Viewer
-销毁时会释放已经加载的环境纹理；加载失败时保留原场景背景并在控制台输出警告。
-
-如果业务需要调整 CAD 文字构建参数，应在第一次文字请求前调用全局初始化入口：
-
-```ts
-import { configureViewerText, createViewer } from '@nebula-spatial/viewer';
-
-configureViewerText({
-  defaultFontURL: '/fonts/cad-fallback.ttf',
-  useWorker: true,
-  sdfGlyphSize: 64,
-  textureWidth: 2048,
-});
-```
-
-`configureViewerText()` 配置的是 Viewer 内部 `cad-loader` 使用的 Troika 模块实例，沿用
-Troika 全局、模块级、一次性配置语义。字体资源和 `resolveTextFont` 映射策略由业务提供；
-如果不调用该方法，Viewer 不会注入额外默认值，Troika 的原有行为保持不变。
-
-几何准备 Worker 默认从 Viewer npm 包内的相对资源路径加载，支持应用部署在子路径。
-需要自行托管 Worker 或满足特定 CSP 时，可通过 `CadOpenOptions.workerUrl` 或
-`workerFactory` 覆盖 Worker 创建方式。
-
-`CadLoadSource` 支持 URL、`ArrayBuffer`、`File` 及对应的 `{ kind: ... }` 形式。`open()`
-会替换当前 CAD 文档；调用 `viewer.cad.close()` 可仅关闭文档并保留 Viewer。
-
-`viewer.cad` 暴露以下只读模型，可通过 `document-change`、`layer-change`、
-`block-change`、`inspector-change` 和 `hud-change` 绑定到产品 UI：
-
-- `document`：文档信息、加载阶段和 `units`（`source`；若 pack 提供则包含 `scaleToMeters`）。
-- `layers`：图层可见性与颜色覆盖。
-- `blocks`：INSERT 使用项和实例可见性。
-- `inspector`：当前 CAD INSERT 或文本选择。
-- `hud`：视图与渲染统计。
-
-CAD 文档的外部 block sidecar 按初始视口需求并行加载，并在首批资源就绪后渐进呈现；后续批次
-会在不打断交互的情况下追加到当前文档。
-
-可选的 `ui` 配置会挂载 `cad-readonly` 预设 UI；产品层也可以完全自行呈现这些模型。
-
-内置 UI 的文案和单位格式化通过稳定配置入口覆盖，不需要依赖 Shadow DOM 内部 class：
-
-```ts
-const viewer = createViewer({
-  viewport,
-  canvas,
-  ui: {
-    root: document.querySelector('#viewer-ui')!,
-    locale: 'en-US',
-    messages: { 'toolbar.fit': 'Frame' },
-    unitFormatter: (value, { unit }) => `${value.toFixed(2)} ${unit}`,
-  },
-});
-```
-
-消息解析优先级为 `messageResolver`、`messages`、内置 locale fallback；`unitFormatter` 会
-覆盖属性面板和比例尺的数值标签。没有传入这些配置时，默认保持简体中文和图纸单位的现有显示。
-
-面板状态默认使用 `nebula-viewer:<instance>:*` 命名空间持久化；可通过 `persistenceKey`
-指定稳定实例标识，或通过同步的 `stateStore.read/write` 接入业务状态存储。设置
-`persistence: false` 会完全关闭状态读写。
-
-内置快捷键默认只绑定到 `viewport`；Viewer 会在该区域内的鼠标/触控操作后将焦点移入该元素，
-因此不会污染页面其它区域的快捷键。不会响应 `input`、`textarea`、`select` 或
-`contenteditable` 内的按键。`keyboard.target` 可指定其它作用域，
-`keyboard.shortcuts.fit` 可修改适应视图按键或设为 `false` 单独关闭。内置 UI 的“适应”按钮和
-快捷键会优先适应当前 CAD 选择；没有选择时才适应整张图纸。
-
-## 通用 Three.js 对象
-
-Viewer 同样可管理非 CAD 的 `Object3D`：
-
-```ts
-viewer.addObject(model, { ownership: 'borrowed' });
-viewer.fitView(model);
-
-const stopPicking = viewer.on('pick', ({ result }) => {
-  selectObject(result?.object ?? null);
-});
-
-viewer.setHighlight(model, { color: 0x5b8cff });
-stopPicking();
-```
-
-`addObject()`、成功的 `removeObject()` 和实际改变可见性的 `setVisible()` 都会发布一次
-`content-change`（`source: 'object'`）。`camera-change` 与 `viewport-change` 同样覆盖没有
-打开 CAD 文档时的用户导航和 resize，便于上层同步小地图、比例尺或协同视角。
-
-默认点击会执行通用 Raycaster 拾取。格式专用的交互可通过 `pointerPick: false` 关闭它，
-并监听 `pointer-click`、`pointer-move` 和 `pointer-leave`。`screenToWorldOnPlane()` 用于
-通用的屏幕坐标到世界平面转换。
-
-## 生命周期
-
-Viewer 借用 `addObject()` 传入的 `Object3D`。`removeObject()` 和 `dispose()` 只解除场景
-挂载，不会释放调用方的 Geometry、Material 或 Texture。
-
-例如，GLTF 资源应在从 Viewer 移除后由加载它的业务统一释放：
-
-```ts
-import { Material, Mesh, Texture } from 'three';
-
-viewer.removeObject(gltf.scene);
-gltf.scene.traverse((object) => {
-  if (!(object instanceof Mesh)) return;
-  object.geometry.dispose();
-  const materials = Array.isArray(object.material) ? object.material : [object.material];
-  for (const material of materials as Material[]) {
-    for (const value of Object.values(material)) {
-      if (value instanceof Texture) value.dispose();
-    }
-    material.dispose();
-  }
-});
-```
-
-Viewer 自行拥有 SceneRuntime、Renderer、Camera、Controls、事件监听和 CAD 会话；调用
-`dispose()` 会统一释放这些资源。运行时依赖为 `three` peer dependency，要求 Node.js 18
-或更高版本。
-
-## 开发
-
-```bash
-npm run typecheck --workspace @nebula-spatial/viewer
-npm test --workspace @nebula-spatial/viewer
-npm run build --workspace @nebula-spatial/viewer
-```
+对于私有 OSS/S3/CDN，常见的预签名 URL 只授权一个具体 Object Key。`root.usd` 的签名通常不能
+复用于 `asset.usdc`、`physics/physics.usda`、纹理等兄弟资源，也不能把入口 URL 的 query
+原样拼接到其他路径。`resourceResolver.resolve(path)` 必须为每个 `path` 返回独立有效的签名 URL
+或已经取得的 `Blob`；入口 URL 自身也必须仍在有效期内。USD loader 会先提取分层 USD 的外部
+引用，再通过该 resolver 递归取得 layer、mesh、material 和 texture 资源；任一依赖返回 401/403
+都会作为鉴权加载失败报告，不会进入视觉降级流程。
+
+`{ kind: 'files', files, entry }` 只表示浏览器已经持有的本地 `File | Blob` 文件包，不能把远端
+URL 字符串放进 `files[].file`。业务层负责入口选择、必要的格式判断、鉴权和依赖映射；不能只依赖
+Viewer 自动识别所有资产形态，也不能把本地样本验证等同于任意远端资产都兼容。普通 glTF 的
+外部资源仍由 `GLTFLoader` 按 URL 请求，不应假设所有格式的子资源都经过 `resourceResolver`；
+私有 glTF 资产优先采用同源/签名目录，或交付为 GLB。
+
+OpenUSD 使用 pthread WASM，部署必须在安全上下文中提供以下响应头：
+
+```text
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+`@mujoco/mujoco` 和 `@openusd-wasm/three-loader` 保持动态加载。Vite 浏览器构建需要将 MuJoCo
+包中的 Node-only 裸模块 `module` 精确 alias 到一个导出 `createRequire()` 的浏览器拒绝模块；
+仓库的 `vite.config.ts` 和独立消费者验证脚本包含该配置。可通过 `assets.mujocoBaseUrl` 与
+`assets.openUsdBaseUrl` 指向自行托管的 runtime 文件目录。
+
+## CAD 快速开始
+
+```ts
+import { createViewer } from '@nebula-spatial/viewer';
+
+const viewer = createViewer({
+  viewport: document.querySelector<HTMLElement>('#viewport')!,
+  canvas: document.querySelector<HTMLCanvasElement>('#viewport canvas')!,
+  initialViewMode: '2d',
+});
+
+viewer.cad.on('document-change', ({ document }) => {
+  updateDocumentTitle(document?.filename ?? '');
+});
+
+const asset = viewer.openAsset('/api/files/demo/result', {
+  format: 'cad',
+  filename: 'demo.dxf',
+  cad: {
+    documentKey: 'demo',
+  },
+});
+
+await asset.ready;
+const document = viewer.cad.document;
+if (!document) throw new Error('CAD document was not opened');
+
+viewer.dispose();
+```
+
+Viewer 默认使用 Three.js 内置 `RoomEnvironment` 提供基于图像的环境光，不会替换场景背景。
+普通 GLTF/GLB 预览使用该环境光，保留舞台地面、反射和主光阴影，关闭仿真专用的半球光与轮廓光。
+仿真资产继续使用自身灯光配置。传入 HDR 时，普通模型使用该 HDR 替代 RoomEnvironment。
+外部系统也可以传入自己的等距柱状 HDR URL：
+
+```ts
+const viewer = createViewer({
+  viewport,
+  canvas,
+  environment: {
+    type: 'hdr',
+    url: 'https://static.example.com/environments/studio.hdr',
+  },
+});
+```
+
+HDR 资源由浏览器直接请求，因此资源服务器需要允许当前应用域名进行 CORS 访问。Viewer
+销毁时会释放已经加载的环境纹理；加载失败时保留原场景背景并在控制台输出警告。
+
+如果业务需要调整 CAD 文字构建参数，应在第一次文字请求前调用全局初始化入口：
+
+```ts
+import { configureViewerText, createViewer } from '@nebula-spatial/viewer';
+
+configureViewerText({
+  defaultFontURL: '/fonts/cad-fallback.ttf',
+  useWorker: true,
+  sdfGlyphSize: 64,
+  textureWidth: 2048,
+});
+```
+
+`configureViewerText()` 配置的是 Viewer 内部 `cad-loader` 使用的 Troika 模块实例，沿用
+Troika 全局、模块级、一次性配置语义。字体资源和 `resolveTextFont` 映射策略由业务提供；
+如果不调用该方法，Viewer 不会注入额外默认值，Troika 的原有行为保持不变。
+
+几何准备 Worker 默认从 Viewer npm 包内的相对资源路径加载，支持应用部署在子路径。
+需要自行托管 Worker 或满足特定 CSP 时，可通过 `CadOpenOptions.workerUrl` 或
+`workerFactory` 覆盖 Worker 创建方式。
+
+`CadLoadSource` 支持 URL、`ArrayBuffer`、`File` 及对应的 `{ kind: ... }` 形式。`openAsset()`
+会替换当前活动资产；调用 `viewer.closeAsset()` 关闭活动资产。旧的 `viewer.cad.open()` /
+`viewer.cad.close()` 会保留兼容行为，但已标记为 deprecated；新代码不应再使用它们管理生命周期。
+
+`viewer.cad` 暴露以下只读模型，可通过 `document-change`、`layer-change`、
+`block-change`、`inspector-change` 和 `hud-change` 绑定到产品 UI：
+
+- `document`：文档信息、加载阶段和 `units`（`source`；若 pack 提供则包含 `scaleToMeters`）。
+- `layers`：图层可见性与颜色覆盖。
+- `blocks`：INSERT 使用项和实例可见性。
+- `inspector`：当前 CAD INSERT 或文本选择。
+- `hud`：视图与渲染统计。
+
+CAD 文档的外部 block sidecar 按初始视口需求并行加载，并在首批资源就绪后渐进呈现；后续批次
+会在不打断交互的情况下追加到当前文档。
+
+传入 `ui.root` 后，默认 `preset:'auto'`：CAD 资产显示 CAD 面板/HUD，model 与 simulation
+显示右下角 preview 工具栏和加载/失败状态层；两组 UI 按资产 profile 互斥。`preset:'cad-readonly'`
+只注册 CAD UI，`preset:'none'` 完全 headless。`ui.cad.parts` 配置 CAD 部件，`ui.scene.parts` 配置模型/仿真场景控件。
+
+`ui.insetTarget` 默认是 viewport；设为 `'none'` 时 Viewer 只发布 `ui-layout-change` 而不修改元素
+inset。内置 UI 位于 `ui.root` 的 ShadowRoot；第三方贡献点位于 light DOM zone（可通过
+`[data-viewer-zone]` 定位），外观由插件自己负责。
+
+内置 UI 的文案和单位格式化通过稳定配置入口覆盖，不需要依赖 Shadow DOM 内部 class：
+
+```ts
+const viewer = createViewer({
+  viewport,
+  canvas,
+  ui: {
+    root: document.querySelector('#viewer-ui')!,
+    preset: 'auto',
+    insetTarget: document.querySelector('#viewport')!,
+    scene: {
+      parts: { playback: true, ground: true, collision: true },
+    },
+    locale: 'en-US',
+    messages: { 'toolbar.fit': 'Frame' },
+    cad: {
+      unitFormatter: (value, { unit }) => `${value.toFixed(2)} ${unit}`,
+    },
+  },
+});
+```
+
+消息解析优先级为 `messageResolver`、`messages`、内置 locale fallback；`unitFormatter` 会
+覆盖属性面板和比例尺的数值标签。没有传入这些配置时，默认保持简体中文和图纸单位的现有显示。
+
+面板状态默认使用 `nebula-viewer:<instance>:*` 命名空间持久化；可通过 `ui.cad.persistenceKey`
+指定稳定实例标识，或通过同步的 `ui.cad.stateStore.read/write` 接入业务状态存储。设置
+`ui.cad.persistence: false` 会完全关闭状态读写。
+
+内置快捷键默认只绑定到 `viewport`；Viewer 会在该区域内的鼠标/触控操作后将焦点移入该元素，
+因此不会污染页面其它区域的快捷键。不会响应 `input`、`textarea`、`select` 或
+`contenteditable` 内的按键。`ui.cad.keyboard.target` 可指定其它作用域，
+`ui.cad.keyboard.shortcuts.fit` 可修改适应视图按键或设为 `false` 单独关闭。内置 UI 的“适应”按钮和
+快捷键会优先适应当前 CAD 选择；没有选择时才适应整张图纸。
+
+## 从 0.3 迁移到 0.4
+
+0.4.0 不只是增加若干格式，而是把 Viewer 从 CAD 为主的 facade 调整为 CAD、3D 模型和仿真资产的
+统一预览运行时。模型与仿真共享同一个 SceneRuntime、Renderer、Camera、environment、导航和 RAF；
+MuJoCo/OpenUSD 只负责格式解析、物理运行和 session 更新，不再拥有第二套页面渲染循环。
+
+### 1. 统一资产生命周期
+
+```ts
+// 0.3：CAD 专属打开入口
+const document = await viewer.cad.open(source, cadOptions);
+viewer.cad.close();
+
+// 0.4：所有格式使用同一个生命周期入口
+const asset = viewer.openAsset(source, {
+  format: 'cad',
+  filename: 'drawing.dxf',
+  cad: {
+    documentKey: 'drawing',
+    resolveTextFont,
+  },
+});
+await asset.ready;
+const document = viewer.cad.document;
+await viewer.closeAsset();
+```
+
+`viewer.cad` 没有被删除，它仍是 CAD 文档、图层、选择、HUD 和 CAD 操作的专属能力入口；只有
+open/close 生命周期被提升到 Viewer。`viewer.cad.open()` / `viewer.cad.close()` 暂时兼容并已
+标记 deprecated。GLB/glTF、URDF、MJCF 和 USD 同样通过 `openAsset()` 返回 `AssetPreview`，调用方
+可订阅 snapshot，或使用句柄的 play/pause/reset、地面、碰撞和 up-axis 能力。
+
+### 2. 模型与仿真接入
+
+- 不再由 Embed/业务代码自行创建 GLTFLoader、挂载模型、管理 loading/failed overlay 或维护独立 RAF。
+- GLB/glTF 的 Draco decoder 必须通过 `assets.dracoDecoderPath`（或单次打开选项）由宿主显式配置。
+- URDF/MJCF 需要 MuJoCo runtime，USD 需要 OpenUSD runtime；可用 `assets.mujocoBaseUrl` 与
+  `assets.openUsdBaseUrl` 指向自托管目录。
+- 远端目录型资产传入口文件 URL，并保持相对依赖目录；`{ kind:'files' }` 只用于本地 `File | Blob`
+  文件包。跨域部署还要配置 CORS、MIME 与鉴权；USD 页面必须满足 HTTPS 和 COOP/COEP。
+- `format:'auto'` 只识别明确扩展名/loader match。通用 `.xml`、无扩展名和目录 URL 应显式传 format，
+  不再通过 `unknownFormatPolicy:'cad'` 猜测。
+
+### 3. UI 与主题迁移
+
+- `ui.preset` 默认值改为 `'auto'`，按资产自动激活 CAD 或 scene UI。需要 0.3 CAD-only 行为时显式
+  设置 `preset:'cad-readonly'`；完全自建 UI 使用 `'none'`。
+- CAD 配置迁移到 `ui.cad`，模型/仿真控件配置到 `ui.scene`，详细字段映射见下方表格。
+- 删除 Embed/业务侧重复的 preview toolbar、loading/failed overlay、抓取 pointer 监听和 viewport
+  inset 同步，改由内置插件、LayoutEngine 与 Viewer 内核承担。
+- `ui.theme` 是唯一初始主题来源。内置主题按钮在 Viewer 内部原地切换，不需要 URL 参数、宿主回调
+  或 Embed 调用 `setTheme()`；公开的 `viewer.setTheme()` 只用于可选的外部编程控制。
+
+| 旧配置 | 0.4 配置 |
+| --- | --- |
+| `ui.parts` | `ui.cad.parts` |
+| `ui.persistence` / `ui.persistenceKey` / `ui.stateStore` | `ui.cad.persistence` / `ui.cad.persistenceKey` / `ui.cad.stateStore` |
+| `ui.keyboard` / `ui.unitFormatter` | `ui.cad.keyboard` / `ui.cad.unitFormatter` |
+| `ui.preview.parts` | `ui.scene.parts` |
+| `ui.preview.appearance.theme` | `ui.theme`，唯一初始主题来源 |
+
+CAD 类型改为 `ViewerCadUiOptions`、`ViewerCadUiParts`、`ViewerCadUiKeyboardOptions`、
+`ViewerCadUiStateStore`；场景类型使用 `ViewerSceneUiOptions`、`ViewerSceneUiParts`，旧名称不保留别名。
+`ui.scene.parts` 支持 `filename`、`playback`、`reset`、`fit`、`upAxis`、`ground`、`collision`、
+`theme`，默认开启并继续受当前资产 capabilities 门控。
+
+### 4. 插件与事件迁移
+
+- 插件通过 `ctx.asset.$read()` 获取活动资产 snapshot，通过 `ctx.asset.$readControl()` 获取权威控制态。
+- 播放、复位、适应视图、up-axis、地面、碰撞和主题统一通过 `ctx.commands` 发出，并受活动 epoch、
+  ready phase 与 capabilities 门控。
+- 按钮的 pressed 状态以 `asset-control-change` 为唯一真值；不要在插件或业务壳中维护重复状态。
+- 第三方格式通过 `asset-loader` contribution 接入统一 session 生命周期，不应直接访问 Viewer 私有
+  Scene、Renderer、Camera 或创建额外渲染循环。
+
+### 5. 最小迁移检查表
+
+- [ ] 所有资产打开/关闭均已改为 `openAsset()` / `closeAsset()`。
+- [ ] CAD 业务状态仍从 `viewer.cad` 读取，没有把 CAD 专属能力混入通用 asset API。
+- [ ] 旧 `ui.parts`、`ui.preview`、顶层 CAD persistence/keyboard 配置已完成分组迁移。
+- [ ] Embed 中重复 UI、GLTF 加载、clearColor 分支、抓取监听和 resize/inset 状态机已移除。
+- [ ] Draco、MuJoCo、OpenUSD runtime URL 由宿主明确配置并已在真实部署路径验证。
+- [ ] 远端资产的 CORS、MIME、鉴权、相对资源路径以及 USD 的跨源隔离已端到端验证。
+
+## 通用 Three.js 对象
+
+Viewer 同样可管理非 CAD 的 `Object3D`：
+
+```ts
+viewer.addObject(model, { ownership: 'borrowed' });
+viewer.fitView(model);
+
+const stopPicking = viewer.on('pick', ({ result }) => {
+  selectObject(result?.object ?? null);
+});
+
+viewer.setHighlight(model, { color: 0x5b8cff });
+stopPicking();
+```
+
+`addObject()`、成功的 `removeObject()` 和实际改变可见性的 `setVisible()` 都会发布一次
+`content-change`（`source: 'object'`）。`camera-change` 与 `viewport-change` 同样覆盖没有
+打开 CAD 文档时的用户导航和 resize，便于上层同步小地图、比例尺或协同视角。
+
+默认点击会执行通用 Raycaster 拾取。格式专用的交互可通过 `pointerPick: false` 关闭它，
+并监听 `pointer-click`、`pointer-move` 和 `pointer-leave`。`screenToWorldOnPlane()` 用于
+通用的屏幕坐标到世界平面转换。
+
+## 生命周期
+
+Viewer 借用 `addObject()` 传入的 `Object3D`。`removeObject()` 和 `dispose()` 只解除场景
+挂载，不会释放调用方的 Geometry、Material 或 Texture。
+
+例如，GLTF 资源应在从 Viewer 移除后由加载它的业务统一释放：
+
+```ts
+import { Material, Mesh, Texture } from 'three';
+
+viewer.removeObject(gltf.scene);
+gltf.scene.traverse((object) => {
+  if (!(object instanceof Mesh)) return;
+  object.geometry.dispose();
+  const materials = Array.isArray(object.material) ? object.material : [object.material];
+  for (const material of materials as Material[]) {
+    for (const value of Object.values(material)) {
+      if (value instanceof Texture) value.dispose();
+    }
+    material.dispose();
+  }
+});
+```
+
+Viewer 自行拥有 SceneRuntime、Renderer、Camera、Controls、事件监听和 CAD 会话；调用
+`dispose()` 会统一释放这些资源。运行时依赖为 `three` peer dependency，要求 Node.js 18
+或更高版本。
+
+## 开发
+
+```bash
+npm run typecheck --workspace @nebula-spatial/viewer
+npm test --workspace @nebula-spatial/viewer
+npm run build --workspace @nebula-spatial/viewer
+```
+
+
+### USD / Isaac Sim 物理映射边界
+
+查看器遵循 OpenUSD `UsdPhysics` 的基础刚体语义：`PhysicsCollisionAPI` 单独应用表示静态碰撞体，和 `PhysicsRigidBodyAPI` 同时应用表示动态刚体；同一刚体下可以包含多个碰撞形状。场景单位、Z/Y-up、Cube/Sphere/Cylinder/Capsule/Mesh 碰撞体、静态碰撞体、质量/密度、自由刚体初始速度和基础关节会在可验证的范围内映射到 MuJoCo。
+
+Isaac Sim/PhysX 专有的碰撞近似、碰撞组、simulation owner、求解器/CCD、接触模型和逐对关节碰撞过滤不保证等价转换。无法可靠映射的属性会写入 `diagnostics.droppedFeatures`，不会伪造一个看似正确的 MJCF 结果；若基础几何或刚体语义无法建立，则按 USD 物理降级策略处理。