@nebula-spatial/viewer 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,49 +1,99 @@
-# Changelog
-
-All notable changes to this package are documented in this file.
-
-## 0.3.0
-
-- 新增 `ViewerPlugin`、`ViewerPluginContext`、8 类贡献点及 `viewer.use()` / `viewer.plugins` 生命周期管理。
-- 新增 `cadInteraction: 'managed' | 'manual' | 'disabled'`、统一 `hitTest/select/clearSelection`、overlay 原语和 camera state API。
-- `camera.setState()` 当前只承诺立即应用经过校验的快照；动画相机切换保留到后续 P2 能力。
-- **Breaking:** 删除 `pickTextAtScreen`、`selectInsert`、`setTextSelection` 三套旧选择入口；迁移为 `hitTest()` 获取 `CadHit`，再调用 `select(hit ? { kind: hit.kind, selection: hit.selection } : null)` 或 `clearSelection()`。
-- 补齐 CAD 公共类型导出、状态 `revision`、图层确定性可见性命令、同步 `CameraStateStore`、加载进度/结构化错误事件。
-- 无参 `fitView()` 现在适配全部内容；需要聚焦 CAD 选择时使用 `viewer.cad.fitSelection()`。
-- `cad-readonly` UI 作为内置插件注册，并支持语义 tokens、style 逃生舱、实例隔离持久化和 `ui-layout-change` 事件。
-- 内置 UI 文案支持 `locale`、`messages`、`messageResolver`，属性面板与比例尺支持 `unitFormatter`。
-- `addObject(object, { ownership: 'borrowed' })` 明确由调用方持有并释放 Object3D 的 GPU 资源。
-
-## 0.2.4
-
-- Keep `@nebula-spatial/cad-loader` as an external runtime dependency so compatible loader updates can be installed independently.
-- Expose `configureViewerText()` as the explicit global Troika text-builder initialization entry point.
-- Render staged external CAD block batches as they become available while preserving active downloads during interaction.
-
-## 0.2.3
-
-- Start rendering base CAD geometry before external block sidecars finish loading.
-- Reuse the CAD geometry Worker and retained main buffer during incremental variant loading.
-- Expose CAD session load timing through the public viewer CAD document model.
-
-## 0.2.2
-
-- Refreshed selected INSERT details and overlays when incremental CAD content expands their bounding boxes.
-
-## 0.2.1
-
-- Resolved the geometry preparation Worker from the published package instead of the site root.
-- Added `CadOpenOptions.workerUrl` and `workerFactory` for custom Worker hosting.
-- Use the built-in room environment by default and support external HDR URLs through `ViewerOptions.environment`.
-
-## 0.2.0
-
-- Added `viewer.cad` for opening, closing, and observing CAD documents.
-- Added CAD document, layer, block, inspector, HUD, camera state, and optional read-only UI models.
-- Added pointer, viewport, interaction, content, and camera lifecycle events.
-- Added the runtime dependency on `@nebula-spatial/cad-loader` for CAD document support.
-- Retained the existing generic Three.js object management and picking APIs.
-
-## 0.1.0
-
-- Initial public release of the read-only Three.js Viewer facade.
+# Changelog
+
+All notable changes to this package are documented in this file.
+
+## 0.4.1
+
+### Added
+
+- 内置普通模型预览新增 FBX 格式，支持按 `.fbx` 扩展名自动识别，并复用模型舞台、相机适配、up-axis 切换和资源释放契约；FBX 优先按文件 `GlobalSettings` 的正向 Y/Z up-axis 声明转换到 Viewer 的 Z-up 世界，无法判断时回退 Y-up，并可由显式 `upAxis` 覆盖；FBXLoader 生成的传统 Lambert/Phong 材质会转换为可由 Viewer 环境光照明的 PBR 材质。
+
+## 0.4.0
+
+0.4.0 将 Viewer 从以 CAD 为主的 facade 扩展为统一资产预览器，并把 3D 模型与仿真资产接入同一个 Three.js 场景、相机、渲染器和帧循环。CAD 专属状态仍保留在 `viewer.cad`，但资产生命周期、内置 UI、加载状态和扩展机制已统一。
+
+### Breaking changes
+
+- CAD、3D 模型和仿真资产统一使用 `viewer.openAsset()` / `viewer.closeAsset()` 管理生命周期。`viewer.cad.open()` / `viewer.cad.close()` 仅为迁移兼容保留并标记为 deprecated。
+- `ui.preset` 默认值从仅 CAD UI 改为 `'auto'`，Viewer 会按活动资产在 CAD UI 与 model/simulation scene UI 之间切换；需要 0.3 CAD-only 行为时显式传 `preset: 'cad-readonly'`。
+- CAD 专属 UI 配置由 `ui.parts`、`ui.persistence*`、`ui.stateStore`、`ui.keyboard`、`ui.unitFormatter` 迁移到 `ui.cad.*`；模型/仿真控件使用 `ui.scene.parts`。相关类型重命名为 `ViewerCadUi*` / `ViewerSceneUi*`，旧名称不保留别名。
+- 主题只有一个初始配置来源 `ui.theme`；`ui.scene.parts.theme` 只控制主题按钮显隐。内置按钮在 Viewer 内部运行时切换主题，不再要求 Embed、URL 参数或宿主回调参与。
+- 自动格式识别不再回退到 CAD。`unknownFormatPolicy` 已 deprecated；通用 `.xml`、无扩展名或目录 URL 必须由调用方显式指定 `format`。
+
+### Added
+
+- 新增统一资产 API 与公开类型：`AssetSource`、`OpenAssetOptions`、`AssetPreview`、`AssetPreviewSnapshot`、`AssetPreviewCapabilities`、`AssetControlState`、`ViewerAssetOptions` 以及 `asset-change`、`asset-error`、`asset-control-change` 事件。
+- 内置支持 CAD、GLB/glTF、URDF、MJCF、USD/USDA/USDC/USDZ；URDF/MJCF 通过 MuJoCo 运行，USD 支持静态视觉和可可靠映射的物理语义。
+- 新增模型 authored up-axis 运行时切换、地面显隐、仿真播放/暂停/复位、碰撞代理、物理属性读取和物理抓取施力；普通/Shift 施力连线分别使用 `#21C7BE` / `#5B8DEF`。
+- 新增 `asset-loader` 插件贡献点、`ctx.asset.$read()` / `$readControl()`、能力门控资产命令和权威控制态广播，第三方格式可沿统一会话契约扩展。
+- 新增 `ViewerLayoutEngine`、五类 zone、`ui.insetTarget` 和内置 CAD/scene UI 插件组；loading、失败提示和 scene toolbar 由包内插件统一提供。
+- 新增运行时 `viewer.setTheme(theme)` 作为可选的外部编程控制入口；常规内置主题切换无需宿主调用。
+- 新增 `assets.dracoDecoderPath`、`assets.mujocoBaseUrl`、`assets.openUsdBaseUrl`，以及单次打开可覆盖的 `baseUrl` / `resourceResolver` 和对应 runtime URL。
+
+### Changed
+
+- 3D 模型与仿真资产共享 Viewer 唯一的 SceneRuntime、Renderer、Camera、environment、预览导航、舞台光照/地面和 RAF；仿真 session 只向统一帧循环提供动态更新，不创建第二套渲染底层。
+- 模型与仿真视觉对象统一通过受控 `Object3D` 挂载通道进入场景；GPU、WASM、object URL 和物理运行时由各资产 session 单一负责释放。
+- 资产 presentation profile 受控应用 view mode、导航策略、clear color、stage theme、fit policy 和 UI profile；关闭或替换资产时恢复宿主默认展示状态。
+- 内置 UI 统一位于 `ui.root` ShadowRoot，第三方贡献点位于 light DOM zone；insets、resize、pointer capture、cursor 和仿真抓取时的导航门控由 Viewer 管理。
+- 远端 URDF/MJCF/glTF 依赖按入口 URL 与 `baseUrl` 解析；远端 USD 以根文件完整 URL 作为相对子层、纹理和引用的解析基址。远端多文件资产仍要求服务器保持路径结构、正确 CORS/MIME/鉴权配置，不能把 CDN 目录 URL 当作可枚举文件包。
+- OpenUSD pthread WASM 仅在 USD 路径要求安全上下文与 COOP/COEP；MuJoCo/OpenUSD 继续动态加载，避免 CAD/普通模型入口提前加载仿真运行时。
+
+### Removed
+
+- 从 Embed/业务壳移除重复的 GLTF 加载、preview toolbar、loading/failed overlay、资产类型 clearColor 分支、抓取 pointer 管线和 ResizeObserver/insets 状态机。
+- 移除模型/仿真独立渲染循环与页面壳状态的设计需求；动态仿真更新现由 Viewer 主循环调度。
+
+### Migration summary
+
+1. 把 CAD 的 `viewer.cad.open/close` 改为 `viewer.openAsset(..., { format: 'cad', cad: {...} })` 与 `viewer.closeAsset()`；CAD 图层、选择和文档状态仍从 `viewer.cad` 读取。
+2. 把宿主自行加载并 `addObject()` 的常规 GLB/glTF 预览迁移到 `openAsset()`，并显式配置 Draco decoder 路径。
+3. 将旧 UI 配置移动到 `ui.cad` / `ui.scene`，删除 Embed 中与内置 UI 重复的 DOM、样式和事件状态机。
+4. 插件改读 `ctx.asset`，通过 `ctx.commands` 控制活动资产，并以 `asset-control-change` 作为按钮 pressed 状态的唯一真值来源。
+5. 为 URDF/MJCF/USD 部署 MuJoCo/OpenUSD runtime；远端资产配置 CORS、MIME、鉴权与相对资源路径，USD 页面同时满足 HTTPS 和 COOP/COEP。
+
+## 0.3.0
+
+- 新增 `ViewerPlugin`、`ViewerPluginContext`、8 类贡献点及 `viewer.use()` / `viewer.plugins` 生命周期管理。
+- 新增 `cadInteraction: 'managed' | 'manual' | 'disabled'`、统一 `hitTest/select/clearSelection`、overlay 原语和 camera state API。
+- `camera.setState()` 当前只承诺立即应用经过校验的快照；动画相机切换保留到后续 P2 能力。
+- **Breaking:** 删除 `pickTextAtScreen`、`selectInsert`、`setTextSelection` 三套旧选择入口；迁移为 `hitTest()` 获取 `CadHit`，再调用 `select(hit ? { kind: hit.kind, selection: hit.selection } : null)` 或 `clearSelection()`。
+- 补齐 CAD 公共类型导出、状态 `revision`、图层确定性可见性命令、同步 `CameraStateStore`、加载进度/结构化错误事件。
+- 无参 `fitView()` 现在适配全部内容；需要聚焦 CAD 选择时使用 `viewer.cad.fitSelection()`。
+- `cad-readonly` UI 作为内置插件注册，并支持语义 tokens、style 逃生舱、实例隔离持久化和 `ui-layout-change` 事件。
+- 内置 UI 文案支持 `locale`、`messages`、`messageResolver`，属性面板与比例尺支持 `unitFormatter`。
+- `addObject(object, { ownership: 'borrowed' })` 明确由调用方持有并释放 Object3D 的 GPU 资源。
+
+## 0.2.4
+
+- Keep `@nebula-spatial/cad-loader` as an external runtime dependency so compatible loader updates can be installed independently.
+- Expose `configureViewerText()` as the explicit global Troika text-builder initialization entry point.
+- Render staged external CAD block batches as they become available while preserving active downloads during interaction.
+
+## 0.2.3
+
+- Start rendering base CAD geometry before external block sidecars finish loading.
+- Reuse the CAD geometry Worker and retained main buffer during incremental variant loading.
+- Expose CAD session load timing through the public viewer CAD document model.
+
+## 0.2.2
+
+- Refreshed selected INSERT details and overlays when incremental CAD content expands their bounding boxes.
+
+## 0.2.1
+
+- Resolved the geometry preparation Worker from the published package instead of the site root.
+- Added `CadOpenOptions.workerUrl` and `workerFactory` for custom Worker hosting.
+- Use the built-in room environment by default and support external HDR URLs through `ViewerOptions.environment`.
+
+## 0.2.0
+
+- Added `viewer.cad` for opening, closing, and observing CAD documents.
+- Added CAD document, layer, block, inspector, HUD, camera state, and optional read-only UI models.
+- Added pointer, viewport, interaction, content, and camera lifecycle events.
+- Added the runtime dependency on `@nebula-spatial/cad-loader` for CAD document support.
+- Retained the existing generic Three.js object management and picking APIs.
+
+## 0.1.0
+
+- Initial public release of the read-only Three.js Viewer facade.