@nebula-spatial/viewer 0.2.4 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 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.

package/README.md

@@ -5,6 +5,54 @@
 
 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 会被拒绝。
+
+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
@@ -72,7 +120,7 @@ Troika 全局、模块级、一次性配置语义。字体资源和 `resolveText
 `viewer.cad` 暴露以下只读模型，可通过 `document-change`、`layer-change`、
 `block-change`、`inspector-change` 和 `hud-change` 绑定到产品 UI：
 
-- `document`：文档信息和加载阶段。
+- `document`：文档信息、加载阶段和 `units`（`source`；若 pack 提供则包含 `scaleToMeters`）。
 - `layers`：图层可见性与颜色覆盖。
 - `blocks`：INSERT 使用项和实例可见性。
 - `inspector`：当前 CAD INSERT 或文本选择。
@@ -83,12 +131,40 @@ 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);
+viewer.addObject(model, { ownership: 'borrowed' });
 viewer.fitView(model);
 
 const stopPicking = viewer.on('pick', ({ result }) => {
@@ -99,6 +175,10 @@ 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()` 用于
 通用的屏幕坐标到世界平面转换。
@@ -108,6 +188,25 @@ stopPicking();
 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
 或更高版本。

package/dist/cad/types.d.ts

@@ -1,6 +1,8 @@
 import type { RenderDebugBreakdownEntry, SplitBlockLayerDetail } from '@nebula-spatial/cad-loader';
 import type { CadSessionLoadTiming } from '@nebula-spatial/cad-loader';
+import type { ViewerViewMode } from '../types';
 export type { CadSessionLoadTiming } from '@nebula-spatial/cad-loader';
+export type { RenderDebugBreakdownEntry, SplitBlockLayerDetail } from '@nebula-spatial/cad-loader';
 export type CadSessionPhase = 'created' | 'header-ready' | 'initial-loading' | 'interactive' | 'failed' | 'disposed';
 export interface CadWorldBounds {
     readonly minX: number;
@@ -70,6 +72,7 @@ export interface CadOpenOptions {
      * enabled; `false` disables background glyph preloading.
      */
     textWarmup?: boolean | CadTextWarmupOptions;
+    signal?: AbortSignal;
 }
 export interface CadDocumentHandle {
     readonly documentKey: string | null;
@@ -77,6 +80,12 @@ export interface CadDocumentHandle {
     readonly phase: CadSessionPhase;
     readonly headerBounds: CadWorldBounds | null;
     readonly layerCount: number;
+    readonly units: CadDocumentUnits;
+}
+export interface CadDocumentUnits {
+    /** Source unit label. Legacy packs without metadata default to `mm`. */
+    readonly source: string;
+    readonly scaleToMeters?: number;
 }
 export interface CadLayerRow {
     readonly index: number;
@@ -87,12 +96,18 @@ export interface CadLayerRow {
 }
 export interface CadLayerModel {
     readonly rows: readonly CadLayerRow[];
-    readonly allColor?: number | null;
+    readonly allColor: number | null;
+    readonly revision: number;
     toggle(index: number): void;
+    setVisible(index: number, visible: boolean): boolean;
+    setVisibleBatch(updates: ReadonlyArray<{
+        index: number;
+        visible: boolean;
+    }>): number;
     showAll(): void;
     hideAll(): void;
     setColor(index: number, color: number | null): void;
-    setAllColor?(color: number | null): void;
+    setAllColor(color: number | null): void;
 }
 export interface CadBlockUsageRow {
     readonly insertId: string;
@@ -107,8 +122,9 @@ export interface CadBlockUsageRow {
 }
 export interface CadBlockModel {
     readonly usages: readonly CadBlockUsageRow[];
+    readonly revision: number;
     toggleInsert(insertId: string, visible?: boolean): void;
-    batchToggleInserts?(updates: ReadonlyArray<{
+    batchToggleInserts(updates: ReadonlyArray<{
         insertId: string;
         visible: boolean;
     }>): void;
@@ -159,19 +175,23 @@ export interface CadInsertDetails {
         readonly maxY: number;
     };
 }
-export interface CadInspectorModel {
+export interface CadInspectorSnapshot {
     readonly selection: CadInsertSelection | null;
     readonly details: CadInsertDetails | null;
-    /** Optional so existing inspector consumers remain source-compatible. */
-    readonly textSelection?: CadTextSelection | null;
-    readonly textDetails?: CadTextDetails | null;
+    readonly textSelection: CadTextSelection | null;
+    readonly textDetails: CadTextDetails | null;
+    readonly revision: number;
+}
+/** Live inspector model. Subscribe to `inspector-change` before reading it reactively. */
+export interface CadInspectorModel extends CadInspectorSnapshot {
 }
 export interface CadScaleRulerState {
     readonly visible: boolean;
     readonly lengthLabel: string;
     readonly worldLength: number;
 }
-export interface CadHudModel {
+export interface CadHudSnapshot {
+    readonly revision: number;
     readonly filename: string | null;
     readonly fileCount: number;
     readonly visibleLayerCount: number;
@@ -198,6 +218,9 @@ export interface CadHudModel {
     readonly splitBlockLayerDetails: readonly SplitBlockLayerDetail[];
     readonly phase: CadSessionPhase | null;
 }
+/** Live HUD model. Subscribe to `hud-change` before reading it reactively. */
+export interface CadHudModel extends CadHudSnapshot {
+}
 export interface CadViewerEventMap {
     'document-change': {
         document: CadDocumentHandle | null;
@@ -217,6 +240,55 @@ export interface CadViewerEventMap {
     'load-timing': {
         timing: CadSessionLoadTiming;
     };
+    'load-progress': CadLoadProgress;
+    error: CadViewerErrorEvent;
+}
+export interface CadLoadProgress {
+    readonly phase: CadSessionPhase;
+    readonly progress: number;
+    readonly pending: number;
+    readonly loaded: number;
+    readonly settled: boolean;
+}
+export type CadViewerErrorCode = 'E_SOURCE' | 'E_FETCH' | 'E_PARSE_HEADER' | 'E_PARSE_GEOMETRY' | 'E_WORKER' | 'E_SIDECAR_FETCH' | 'E_ANNOTATION' | 'E_FONT' | 'E_ABORTED' | 'E_SUPERSEDED';
+export interface CadViewerErrorEvent {
+    readonly code: CadViewerErrorCode;
+    readonly stage: 'source' | 'header' | 'geometry' | 'worker' | 'sidecar' | 'annotation' | 'font' | 'lifecycle';
+    readonly fatal: boolean;
+    readonly source: CadLoadSource | null;
+    readonly error: Error;
+}
+export type CadSelection = {
+    readonly kind: 'insert';
+    readonly selection: CadInsertSelection;
+} | {
+    readonly kind: 'text';
+    readonly selection: CadTextSelection;
+};
+export type CadHit = {
+    readonly kind: 'insert';
+    readonly selection: CadInsertSelection;
+    readonly details: CadInsertDetails | null;
+} | {
+    readonly kind: 'text';
+    readonly selection: CadTextSelection;
+    readonly details: CadTextDetails | null;
+};
+export interface CadViewerSnapshot {
+    readonly revision: number;
+    readonly document: CadDocumentHandle | null;
+    readonly layers: {
+        readonly rows: readonly CadLayerRow[];
+        readonly allColor: number | null;
+        readonly revision: number;
+    };
+    readonly blocks: {
+        readonly usages: readonly CadBlockUsageRow[];
+        readonly revision: number;
+    };
+    readonly inspector: CadInspectorSnapshot;
+    readonly hud: CadHudSnapshot;
+    readonly loadTiming: CadSessionLoadTiming | null;
 }
 export interface CadViewerCapability {
     readonly document: CadDocumentHandle | null;
@@ -225,15 +297,23 @@ export interface CadViewerCapability {
     readonly inspector: CadInspectorModel;
     readonly hud: CadHudModel;
     readonly loadTiming: CadSessionLoadTiming | null;
+    readonly capabilities: {
+        readonly insertSelection: true;
+        readonly textSelection: true;
+        readonly insertPreview: true;
+        readonly batchVisibility: true;
+    };
     open(source: CadLoadSource, options?: CadOpenOptions): Promise<CadDocumentHandle>;
     close(): void;
-    selectInsert?(insertId: string | null): void;
     renderInsertPreview(canvas: HTMLCanvasElement): boolean;
-    pickTextAtScreen?(clientX: number, clientY: number): {
-        selection: CadTextSelection;
-        details: CadTextDetails | null;
-    } | null;
-    setTextSelection?(selection: CadTextSelection | null, details: CadTextDetails | null): void;
+    hitTest(clientX: number, clientY: number, options?: {
+        readonly kinds?: readonly ('insert' | 'text')[];
+    }): CadHit | null;
+    select(selection: CadSelection | null): void;
+    clearSelection(): void;
+    getSnapshot(): CadViewerSnapshot;
+    fitDocument(): boolean;
+    fitSelection(): boolean;
     on<K extends keyof CadViewerEventMap>(type: K, listener: (event: CadViewerEventMap[K]) => void): () => void;
 }
 export type ViewerUiPreset = 'cad-readonly';
@@ -257,8 +337,46 @@ export interface ViewerUiOptions {
     preset?: ViewerUiPreset;
     parts?: ViewerUiParts;
     theme?: ViewerUiTheme;
+    tokens?: ViewerUiTokens;
+    style?: string | ((root: ShadowRoot) => void);
+    persistence?: boolean;
+    persistenceKey?: string;
+    stateStore?: ViewerUiStateStore;
+    keyboard?: ViewerUiKeyboardOptions;
+    locale?: string;
+    messages?: Readonly<Record<string, string>>;
+    messageResolver?: (key: string, params?: Readonly<Record<string, string | number>>) => string | undefined;
+    unitFormatter?: (value: number, context: {
+        readonly unit: string;
+        readonly viewMode: ViewerViewMode;
+    }) => string;
+}
+export interface ViewerUiStateStore {
+    read(key: string): string | null;
+    write(key: string, value: string): void;
+}
+export interface ViewerUiKeyboardOptions {
+    enabled?: boolean;
+    /**
+     * Restrict shortcuts to this element. A pointer interaction inside it focuses
+     * the target unless the interaction began in an editable control.
+     */
+    target?: HTMLElement;
+    shortcuts?: {
+        /** Key used by the built-in fit command. Defaults to `f`; `false` disables it. */
+        fit?: string | false;
+    };
+}
+export interface ViewerUiTokens {
+    accent?: string;
+    panelBackground?: string;
+    background?: string;
+    text?: string;
+    textDim?: string;
+    border?: string;
+    hudBackground?: string;
 }
 export interface CameraStateStore {
-    read(key: string): Promise<unknown> | unknown;
-    write(key: string, value: unknown): Promise<void> | void;
+    read(key: string): unknown | null;
+    write(key: string, value: unknown): void;
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { createViewer } from './viewer';
+export type { Disposable, ToolbarItem, ViewerState, ViewerInteractionHooks, ViewerContributionPoint, ViewerPlugin, ViewerPluginContext, ViewerPluginRegistry, } from './plugins';
 export { configureViewerText } from './cad/text';
 export type { ViewerTextBuilderOptions } from './cad/text';
-export type { CadBlockModel, CadDocumentHandle, CadFontResolver, CadResolvedTextFont, CadHudModel, CadInspectorModel, CadLayerModel, CadLoadSource, CadOpenOptions, CadSessionLoadTiming, CadTextDetails, CadTextSelection, CadTextSelectionId, CadViewerCapability, ResolveTextFont, CadViewerEventMap, CameraStateStore, Viewer, ViewerEventMap, ViewerEnvironment, ViewerFitViewOptions, ViewerHighlightOptions, ViewerOptions, ViewerPickOptions, ViewerPickResult, ViewerPointerEvent, ViewerUiOptions, ViewerUiParts, ViewerUiPreset, ViewerUiTheme, ViewerViewMode, } from './types';
+export type { CadBlockModel, CadDocumentHandle, CadDocumentUnits, CadFontResolver, CadFontRequest, CadResolvedFont, CadResolvedTextFont, CadTextWarmupOptions, CadHudModel, CadHudSnapshot, CadInspectorModel, CadInspectorSnapshot, CadLayerModel, CadLayerRow, CadBlockUsageRow, CadSessionPhase, CadWorldBounds, CadScaleRulerState, CadInsertDetails, CadInsertSelection, CadInsertSelectionId, CadTextDetails, CadTextSelection, CadTextSelectionId, CadSelection, CadHit, CadViewerSnapshot, CadLoadProgress, CadViewerErrorCode, CadViewerErrorEvent, CadLoadSource, CadOpenOptions, CadSessionLoadTiming, RenderDebugBreakdownEntry, SplitBlockLayerDetail, CadViewerCapability, ResolveTextFont, CadViewerEventMap, CameraStateStore, Viewer, ViewerEventMap, ViewerEnvironment, ViewerFitViewOptions, ViewerHighlightOptions, ViewerOptions, ViewerPickOptions, ViewerPickResult, ViewerPointerEvent, ViewerObjectOptions, ViewerCameraSnapshot, ViewerOrthographicSnapshot, ViewerOrbitSnapshot, ViewerRenderStats, ViewerDocumentRect, ViewerUiKeyboardOptions, ViewerUiOptions, ViewerUiParts, ViewerUiPreset, ViewerUiStateStore, ViewerUiTheme, ViewerViewMode, CadInteractionMode, CameraChangeReason, ViewerUiTokens, } from './types';