@nebula-spatial/viewer 0.2.4 → 0.3.0

package/dist/plugins.d.ts

@@ -0,0 +1,131 @@
+import type { Box3, Object3D } from 'three';
+import type { CadHit, CadSelection, CadViewerSnapshot, CadViewerEventMap } from './cad/types';
+import type { ViewerEventMap, ViewerViewMode } from './types';
+export interface Disposable {
+    dispose(): void;
+}
+export interface ToolbarItem {
+    readonly id: string;
+    readonly label: string;
+    readonly title?: string;
+    readonly disabled?: boolean;
+    readonly onClick: () => void;
+}
+export interface ViewerState {
+    readonly viewMode: ViewerViewMode;
+    readonly selectedObject: Object3D | null;
+    readonly highlightedObject: Object3D | null;
+    readonly isDisposed: boolean;
+}
+export interface ViewerPluginContext {
+    readonly cad: {
+        $read(): CadViewerSnapshot;
+    };
+    readonly viewer: {
+        $getState(): ViewerState;
+    };
+    readonly commands: {
+        setLayerVisible(index: number, visible: boolean): boolean;
+        setSelection(selection: CadSelection | null): void;
+        fitDocument(): boolean;
+        setViewMode(mode: ViewerViewMode): void;
+    };
+    readonly events: {
+        on<K extends keyof (ViewerEventMap & CadViewerEventMap)>(type: K, listener: (event: (ViewerEventMap & CadViewerEventMap)[K]) => void): () => void;
+    };
+    readonly layout: {
+        mount(node: Node, options?: {
+            position?: 'left' | 'right' | 'top' | 'bottom' | 'overlay';
+        }): Disposable;
+        onInsetsChange(listener: (insets: ViewerEventMap['ui-layout-change']['contentInsets']) => void): () => void;
+    };
+    contribute(point: ViewerContributionPoint): Disposable;
+    dispose(): void;
+}
+export interface ViewerInteractionHooks {
+    /** Return false to consume the interaction and stop the managed pipeline. */
+    onPick?: (hit: CadHit | null) => boolean | void;
+    onHover?: (hit: CadHit | null) => void;
+    onSelect?: (selection: CadSelection | null) => void;
+    onClear?: () => void;
+}
+export type ViewerContributionPoint = {
+    readonly kind: 'panel';
+    readonly id: string;
+    readonly factory: (ctx: ViewerPluginContext) => Node;
+} | {
+    readonly kind: 'toolbar';
+    readonly id: string;
+    readonly items: readonly ToolbarItem[];
+} | {
+    readonly kind: 'hud';
+    readonly id: string;
+    readonly factory: (ctx: ViewerPluginContext) => Node;
+} | {
+    readonly kind: 'statusbar';
+    readonly id: string;
+    readonly factory: (ctx: ViewerPluginContext) => Node;
+} | {
+    readonly kind: 'inspector';
+    readonly id: string;
+    readonly matcher: (selection: CadSelection) => boolean;
+    readonly render: (ctx: ViewerPluginContext, selection: CadSelection) => Node;
+} | {
+    readonly kind: 'interaction';
+    readonly id: string;
+    readonly hooks: ViewerInteractionHooks;
+} | {
+    readonly kind: 'command';
+    readonly id: string;
+    readonly handler: (ctx: ViewerPluginContext, args?: unknown) => void;
+} | {
+    readonly kind: 'fit-policy';
+    readonly id: string;
+    readonly resolve: (ctx: ViewerPluginContext) => Box3 | null;
+};
+export interface ViewerPlugin {
+    readonly id: string;
+    activate(context: ViewerPluginContext): void | Promise<void>;
+    deactivate?(): void | Promise<void>;
+}
+type SnapshotReader = () => CadViewerSnapshot;
+type StateReader = () => ViewerState;
+type PluginEventMap = ViewerEventMap & CadViewerEventMap;
+type EventSubscriber = <K extends keyof PluginEventMap>(type: K, listener: (event: PluginEventMap[K]) => void) => () => void;
+type CommandApi = ViewerPluginContext['commands'];
+export declare class ViewerPluginManager implements ViewerPluginRegistry {
+    private readonly readCad;
+    private readonly readState;
+    private readonly subscribe;
+    private readonly commands;
+    private readonly hostElement;
+    private readonly pluginsById;
+    private readonly contributions;
+    private readonly commandContributions;
+    private refreshingInspectors;
+    private disposed;
+    constructor(readCad: SnapshotReader, readState: StateReader, subscribe: EventSubscriber, commands: CommandApi, hostElement: HTMLElement);
+    register(plugin: ViewerPlugin): Disposable;
+    use(plugins: readonly ViewerPlugin[], options?: {
+        replace?: boolean;
+    }): void;
+    private deactivate;
+    disposeAll(): void;
+    dispose(): void;
+    dispatchInteraction(kind: keyof ViewerInteractionHooks, value: CadHit | CadSelection | null): boolean;
+    findFitPolicy(): Box3 | null;
+    executeCommand(id: string, args?: unknown): boolean;
+    hasCommand(id: string): boolean;
+    private removeContribution;
+    private mountContribution;
+    private isFirstMatchingInspector;
+    private refreshInspectorContributions;
+    private assertActive;
+}
+export interface ViewerPluginRegistry {
+    register(plugin: ViewerPlugin): Disposable;
+    use(plugins: readonly ViewerPlugin[], options?: {
+        replace?: boolean;
+    }): void;
+}
+export {};

package/dist/types.d.ts

@@ -1,7 +1,9 @@
 import type { Box3, ColorRepresentation, Object3D, Vector3 } from 'three';
 import type { CadViewerCapability, CameraStateStore, ViewerUiOptions } from './cad/types';
-export type { CadBlockModel, CadDocumentHandle, CadFontResolver, CadResolvedTextFont, CadHudModel, CadInspectorModel, CadLayerModel, CadLoadSource, CadOpenOptions, CadSessionLoadTiming, CadTextDetails, CadTextSelection, CadTextSelectionId, CadViewerCapability, ResolveTextFont, CadViewerEventMap, CameraStateStore, ViewerUiOptions, ViewerUiParts, ViewerUiPreset, ViewerUiTheme, } from './cad/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, ViewerUiKeyboardOptions, ViewerUiOptions, ViewerUiParts, ViewerUiPreset, ViewerUiStateStore, ViewerUiTheme, ViewerUiTokens, } from './cad/types';
 export type ViewerViewMode = '2d' | '3d';
+export type CadInteractionMode = 'managed' | 'manual' | 'disabled';
+export type CameraChangeReason = 'pointer' | 'wheel' | 'fit' | 'restore' | 'api' | 'view-mode';
 export type ViewerEnvironment = 'room' | {
     /** Load an external equirectangular HDR texture for image-based lighting. */
     readonly type: 'hdr';
@@ -50,6 +52,22 @@ export interface ViewerOptions {
     environment?: ViewerEnvironment;
     autoSelectOnPick?: boolean;
     pointerPick?: boolean;
+    /** CAD click policy. Defaults to managed. */
+    cadInteraction?: CadInteractionMode;
+    cadInteractionStyle?: {
+        hover?: {
+            color?: ColorRepresentation;
+            fillOpacity?: number;
+            edgeOpacity?: number;
+            enabled?: boolean;
+        };
+        selected?: {
+            color?: ColorRepresentation;
+            fillOpacity?: number;
+            edgeOpacity?: number;
+            enabled?: boolean;
+        };
+    };
     cameraStateStore?: CameraStateStore | false;
     /** Max delay for merged viewport demands while the interaction is active. Default 160ms. */
     viewportDemandCoalesceMs?: number;
@@ -75,6 +93,10 @@ export interface ViewerPickResult {
 export interface ViewerHighlightOptions {
     color?: ColorRepresentation;
 }
+export interface ViewerObjectOptions {
+    /** Viewer only mounts the object; the caller retains responsibility for GPU resource disposal. */
+    readonly ownership?: 'borrowed';
+}
 export interface ViewerRenderStats {
     readonly drawCalls: number;
     readonly submittedVertexRefs: number;
@@ -121,6 +143,18 @@ export interface ViewerEventMap {
     };
     'camera-change': {
         viewMode: ViewerViewMode;
+        reason: CameraChangeReason;
+        interaction: 'active' | 'idle';
+    };
+    'ui-layout-change': {
+        contentInsets: {
+            readonly top: number;
+            readonly right: number;
+            readonly bottom: number;
+            readonly left: number;
+        };
+        layerPanelOpen: boolean;
+        propertyPanelOpen: boolean;
     };
 }
 export interface Viewer {
@@ -131,13 +165,33 @@ export interface Viewer {
     readonly highlightedObject: Object3D | null;
     readonly isDisposed: boolean;
     readonly cad: CadViewerCapability;
-    addObject(object: Object3D): void;
+    readonly overlays: {
+        set(key: string, object: Object3D, options?: {
+            owned?: boolean;
+        }): void;
+        remove(key: string, options?: {
+            dispose?: boolean;
+        }): Object3D | null;
+    };
+    readonly camera: {
+        getState(): ViewerCameraSnapshot | null;
+        /** Applies a validated snapshot immediately. Animated transitions are not part of the current contract. */
+        setState(snapshot: ViewerCameraSnapshot): boolean;
+        reset(): boolean;
+    };
+    readonly plugins: import('./plugins').ViewerPluginRegistry;
+    readonly commands: {
+        execute(id: string, args?: unknown): boolean;
+        has(id: string): boolean;
+    };
+    addObject(object: Object3D, options?: ViewerObjectOptions): void;
     removeObject(object: Object3D): boolean;
     setVisible(object: Object3D, visible: boolean): void;
     setViewMode(mode: ViewerViewMode, options?: {
         preserveOrbit?: boolean;
     }): void;
     fitView(target?: Object3D | Box3, options?: ViewerFitViewOptions): boolean;
+    fitAll(options?: ViewerFitViewOptions): boolean;
     screenToWorldOnPlane(clientX: number, clientY: number, planeZ?: number): Vector3 | null;
     pick(clientX: number, clientY: number, options?: ViewerPickOptions): ViewerPickResult | null;
     setSelection(object: Object3D | null): void;
@@ -146,4 +200,7 @@ export interface Viewer {
     resize(): boolean;
     requestRender(): void;
     dispose(): void;
+    use(plugins: readonly import('./plugins').ViewerPlugin[], options?: {
+        replace?: boolean;
+    }): void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebula-spatial/viewer",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Read-only Three.js viewer facade",
   "license": "ISC",
   "engines": {
@@ -36,7 +36,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@nebula-spatial/cad-loader": "^0.2.4"
+    "@nebula-spatial/cad-loader": "^0.3.0"
   },
   "peerDependencies": {
     "three": "0.182.0"