@nebula-spatial/viewer 0.3.0 → 0.4.1

package/dist/assets/types.d.ts

@@ -0,0 +1,235 @@
+import type { Object3D, WebGLRenderer, Scene, Camera, Box3, ColorRepresentation } from 'three';
+import type { CadLoadSource, CadOpenOptions } from '../cad/types';
+import type { ViewerViewMode } from '../types';
+export type AssetPreviewKind = 'cad' | 'model' | 'simulation';
+export type BuiltinAssetFormat = 'cad' | 'glb' | 'gltf' | 'fbx' | 'urdf' | 'mjcf' | 'usd' | 'usda' | 'usdc' | 'usdz';
+export type AssetFormat = BuiltinAssetFormat | (string & {});
+export interface AssetFileEntry {
+    readonly path: string;
+    readonly file: File | Blob;
+}
+export type AssetSource = CadLoadSource | {
+    readonly kind: 'files';
+    readonly files: readonly AssetFileEntry[];
+    readonly entry?: string;
+    readonly signal?: AbortSignal;
+};
+export interface AssetResourceResolver {
+    resolve(path: string, options?: {
+        readonly signal?: AbortSignal;
+    }): string | URL | Blob | Promise<string | URL | Blob>;
+}
+export interface ViewerAssetOptions {
+    readonly dracoDecoderPath?: string;
+    readonly openUsdBaseUrl?: string;
+    readonly mujocoBaseUrl?: string;
+}
+export interface OpenAssetOptions {
+    readonly simulationTheme?: 'dark' | 'light';
+    readonly format?: AssetFormat | 'auto';
+    readonly filename?: string;
+    readonly signal?: AbortSignal;
+    readonly baseUrl?: string;
+    readonly resourceResolver?: AssetResourceResolver;
+    /** @deprecated Auto detection never falls back to CAD; pass an explicit format instead. */
+    readonly unknownFormatPolicy?: 'cad' | 'error';
+    readonly dracoDecoderPath?: string;
+    readonly mujocoBaseUrl?: string;
+    readonly openUsdBaseUrl?: string;
+    /**
+     * Which authored axis is "up" for a plain model asset. FBX first uses a
+     * supported positive Y/Z declaration from GlobalSettings, then falls back to
+     * 'y' when it is missing or cannot be read. GLB/glTF retain the existing 'z'
+     * default for CAD-kernel compatibility. An explicit value always wins. 'y'
+     * rotates the model root into world +Z.
+     * Ignored by simulation assets, whose formats declare their own up axis.
+     */
+    readonly upAxis?: AssetUpAxis;
+    /** CAD-specific compatibility options. `filename` and `signal` above take precedence. */
+    readonly cad?: Omit<CadOpenOptions, 'filename' | 'signal'>;
+}
+/** World axis a model was authored to treat as up. See `OpenAssetOptions.upAxis`. */
+export type AssetUpAxis = 'y' | 'z';
+export interface AssetPreviewCapabilities {
+    readonly canPlay: boolean;
+    readonly canPause: boolean;
+    readonly canReset: boolean;
+    readonly hasPhysics: boolean;
+    /**
+     * A plain model whose authored up axis can be re-oriented at runtime.
+     * Optional (absent means false) so pre-existing third-party asset sessions
+     * that build this literal keep compiling; only the model session opts in.
+     */
+    readonly canReorientUpAxis?: boolean;
+    /**
+     * The staged ground (grid + reflection) can be hidden. Optional, same
+     * rationale as `canReorientUpAxis`; model and simulation sessions opt in.
+     */
+    readonly canToggleGround?: boolean;
+    /**
+     * Authored or runtime collision geometry can be shown independently of
+     * dynamic physics. Static USD stages may declare colliders without rigid
+     * bodies, so this must not be inferred from `hasPhysics`.
+     */
+    readonly canToggleCollision?: boolean;
+}
+export type AssetPreviewPhase = 'detecting' | 'loading' | 'ready' | 'failed' | 'closing' | 'closed';
+export interface AssetErrorSnapshot {
+    readonly code: string;
+    readonly message: string;
+    readonly stage: string;
+    readonly fatal: boolean;
+}
+/** Non-fatal condition that changed how an otherwise usable asset is presented. */
+export interface AssetWarningSnapshot {
+    readonly code: string;
+    readonly message: string;
+    readonly stage: string;
+}
+export interface AssetPreviewSnapshot {
+    readonly revision: number;
+    readonly phase: AssetPreviewPhase;
+    readonly stage?: string;
+    readonly message?: string;
+    readonly format: AssetFormat | null;
+    readonly kind: AssetPreviewKind | null;
+    readonly capabilities: AssetPreviewCapabilities | null;
+    readonly error: AssetErrorSnapshot | null;
+    /** Present when loading succeeded with an explicit, user-visible degradation. */
+    readonly warning?: AssetWarningSnapshot | null;
+    /**
+     * Display name for the asset (`OpenAssetOptions.filename`, else the file name
+     * derived from the normalized source). Hosts should render this rather than
+     * re-deriving a name from the raw URL.
+     */
+    readonly filename: string | null;
+}
+/**
+ * Control state of the active asset. Published on `asset-control-change` so UI
+ * (built-in or plugin) never has to keep its own copy of a pressed state —
+ * whichever entry point changed it, exactly one authoritative value is broadcast.
+ */
+export interface AssetControlState {
+    readonly playing: boolean;
+    readonly groundVisible: boolean;
+    readonly collisionVisible: boolean;
+    readonly upAxis: AssetUpAxis | null;
+}
+export interface AssetPreview {
+    getPhysicsProperties(): Readonly<Record<string, unknown>> | null;
+    setCollisionVisible(visible: boolean): void;
+    /** Re-orients a plain model's authored up axis without moving the camera. */
+    setUpAxis(axis: AssetUpAxis): void;
+    getUpAxis(): AssetUpAxis | null;
+    /** Shows or hides the staged ground (grid + reflection). */
+    setGroundVisible(visible: boolean): void;
+    getGroundVisible(): boolean;
+    readonly id: string;
+    readonly ready: Promise<void>;
+    getSnapshot(): AssetPreviewSnapshot;
+    subscribe(listener: (snapshot: AssetPreviewSnapshot) => void): () => void;
+    close(): Promise<void>;
+    play(): void;
+    pause(): void;
+    reset(): void;
+    beginGrab?(event: PointerEvent, camera: import('three').Camera, canvas: HTMLElement): boolean;
+    moveGrab?(event: PointerEvent, camera: import('three').Camera, canvas: HTMLElement): void;
+    endGrab?(): void;
+}
+export interface AssetPresentationProfile {
+    readonly preferredViewMode?: ViewerViewMode;
+    /**
+     * Canvas clear color while this asset is active. Applied on profile change and
+     * reverted to the `createViewer({ clearColor })` value when no asset owns one,
+     * so hosts no longer need to encode "which asset is this" in their bootstrap.
+     */
+    readonly clearColor?: ColorRepresentation;
+    /** Staged dark/light variant for assets that own a themed stage. */
+    readonly stageTheme?: 'dark' | 'light';
+    readonly interactionMode?: 'cad-managed' | 'object' | 'simulation';
+    readonly uiProfile?: 'cad' | 'model' | 'simulation' | 'none';
+    readonly fitPolicy?: 'restore-then-fit' | 'fit-on-ready' | 'preserve';
+    readonly environmentProfile?: string;
+}
+export interface NormalizedAssetSource {
+    readonly original: AssetSource;
+    readonly entryPath: string | null;
+    readonly filename: string | null;
+    readonly url: string | null;
+    readonly signal: AbortSignal;
+    readonly baseUrl: string | null;
+    readonly hasResourceResolver: boolean;
+    resolve(path: string): Promise<string>;
+    release(): void;
+}
+export interface AssetDetectionResult {
+    readonly format: AssetFormat;
+}
+export interface AssetLoaderContext {
+    readonly signal: AbortSignal;
+    readonly options: OpenAssetOptions;
+    readonly source: NormalizedAssetSource;
+    readonly format: AssetFormat;
+    requestRender(): void;
+    fit(root: Object3D | Box3, options?: {
+        readonly viewMode?: ViewerViewMode;
+        readonly padding?: number;
+    }): boolean;
+    reportError(error: unknown, options: {
+        readonly stage: string;
+        readonly fatal: boolean;
+        readonly code?: string;
+    }): void;
+    reportProgress?(stage: string, message?: string): void;
+}
+export interface AssetSession {
+    setTheme?(theme: 'dark' | 'light'): void;
+    beforeRender?(renderer: WebGLRenderer, scene: Scene, camera: Camera): (() => void) | void;
+    getPhysicsProperties?(): Readonly<Record<string, unknown>> | null;
+    setCollisionVisible?(visible: boolean): void;
+    setUpAxis?(axis: AssetUpAxis): void;
+    getUpAxis?(): AssetUpAxis | null;
+    setGroundVisible?(visible: boolean): void;
+    getGroundVisible?(): boolean;
+    getFitBounds?(): Box3 | null;
+    readonly fitTarget?: Object3D | Box3 | null;
+    readonly id: string;
+    readonly opened: Promise<void>;
+    readonly root?: Object3D | null;
+    readonly capabilities?: AssetPreviewCapabilities;
+    readonly presentation?: AssetPresentationProfile;
+    /** Non-fatal degradation decided by the loader after the session opened. */
+    readonly warning?: AssetWarningSnapshot | null;
+    beginDispose(): void;
+    dispose(): Promise<void>;
+    play?(): void;
+    pause?(): void;
+    reset?(): void;
+    update?(deltaSeconds: number): boolean;
+    beginGrab?(event: PointerEvent, camera: import('three').Camera, canvas: HTMLElement): boolean;
+    moveGrab?(event: PointerEvent, camera: import('three').Camera, canvas: HTMLElement): void;
+    endGrab?(): void;
+}
+export interface AssetLoaderContribution {
+    readonly kind: 'asset-loader';
+    readonly id: string;
+    readonly assetKind: AssetPreviewKind;
+    readonly formats: readonly AssetFormat[];
+    readonly presentation?: AssetPresentationProfile;
+    match?(source: NormalizedAssetSource): AssetDetectionResult | null | Promise<AssetDetectionResult | null>;
+    createSession(source: NormalizedAssetSource, context: AssetLoaderContext): AssetSession | Promise<AssetSession>;
+}
+export interface AssetChangeEvent {
+    readonly sessionId: string;
+    readonly snapshot: AssetPreviewSnapshot;
+}
+export interface AssetControlChangeEvent {
+    readonly sessionId: string;
+    readonly state: AssetControlState;
+}
+export interface AssetErrorEvent extends AssetErrorSnapshot {
+    readonly sessionId: string;
+    readonly format: AssetFormat | null;
+    readonly error: Error;
+}
+export declare const EMPTY_ASSET_CAPABILITIES: AssetPreviewCapabilities;

package/dist/cad/types.d.ts

@@ -1,6 +1,7 @@
 import type { RenderDebugBreakdownEntry, SplitBlockLayerDetail } from '@nebula-spatial/cad-loader';
 import type { CadSessionLoadTiming } from '@nebula-spatial/cad-loader';
 import type { ViewerViewMode } from '../types';
+export type { ViewerUiOptions, ViewerSceneUiOptions, ViewerSceneUiParts, ViewerUiPreset, ViewerUiTheme, ViewerUiTokens } from '../ui/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';
@@ -303,7 +304,14 @@ export interface CadViewerCapability {
         readonly insertPreview: true;
         readonly batchVisibility: true;
     };
+    /**
+     * @deprecated Use `viewer.openAsset(source, { format: 'cad', cad: options })`
+     * and read `viewer.cad.document` after `asset.ready`.
+     */
     open(source: CadLoadSource, options?: CadOpenOptions): Promise<CadDocumentHandle>;
+    /**
+     * @deprecated Use `viewer.closeAsset()` to close the active asset.
+     */
     close(): void;
     renderInsertPreview(canvas: HTMLCanvasElement): boolean;
     hitTest(clientX: number, clientY: number, options?: {
@@ -316,9 +324,7 @@ export interface CadViewerCapability {
     fitSelection(): boolean;
     on<K extends keyof CadViewerEventMap>(type: K, listener: (event: CadViewerEventMap[K]) => void): () => void;
 }
-export type ViewerUiPreset = 'cad-readonly';
-export type ViewerUiTheme = 'dark' | 'light';
-export interface ViewerUiParts {
+export interface ViewerCadUiParts {
     layerPanel?: boolean;
     propertyPanel?: boolean;
     hud?: boolean;
@@ -332,30 +338,23 @@ export interface ViewerUiParts {
     /** Show the Debug details card in the infobar. Default: true. */
     infobarDebug?: boolean;
 }
-export interface ViewerUiOptions {
-    root: HTMLElement;
-    preset?: ViewerUiPreset;
-    parts?: ViewerUiParts;
-    theme?: ViewerUiTheme;
-    tokens?: ViewerUiTokens;
-    style?: string | ((root: ShadowRoot) => void);
+/** Options belonging only to the built-in CAD UI group. */
+export interface ViewerCadUiOptions {
+    parts?: ViewerCadUiParts;
     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;
+    stateStore?: ViewerCadUiStateStore;
+    keyboard?: ViewerCadUiKeyboardOptions;
     unitFormatter?: (value: number, context: {
         readonly unit: string;
         readonly viewMode: ViewerViewMode;
     }) => string;
 }
-export interface ViewerUiStateStore {
+export interface ViewerCadUiStateStore {
     read(key: string): string | null;
     write(key: string, value: string): void;
 }
-export interface ViewerUiKeyboardOptions {
+export interface ViewerCadUiKeyboardOptions {
     enabled?: boolean;
     /**
      * Restrict shortcuts to this element. A pointer interaction inside it focuses
@@ -367,15 +366,6 @@ export interface ViewerUiKeyboardOptions {
         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): unknown | null;
     write(key: string, value: unknown): void;