@nebula-spatial/viewer 0.2.4 → 0.4.0

package/dist/assets/types.d.ts

@@ -0,0 +1,234 @@
+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' | '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. glTF's normative
+     * coordinate system is Y-up, but CAD-kernel exporters emit Z-up files with no
+     * in-file declaration, so this cannot be inferred reliably. Defaults to 'z',
+     * matching the preview world; '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,9 @@
 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';
 export interface CadWorldBounds {
     readonly minX: number;
@@ -70,6 +73,7 @@ export interface CadOpenOptions {
      * enabled; `false` disables background glyph preloading.
      */
     textWarmup?: boolean | CadTextWarmupOptions;
+    signal?: AbortSignal;
 }
 export interface CadDocumentHandle {
     readonly documentKey: string | null;
@@ -77,6 +81,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 +97,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 +123,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 +176,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 +219,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 +241,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,20 +298,33 @@ 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;
+    };
+    /**
+     * @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;
-    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';
-export type ViewerUiTheme = 'dark' | 'light';
-export interface ViewerUiParts {
+export interface ViewerCadUiParts {
     layerPanel?: boolean;
     propertyPanel?: boolean;
     hud?: boolean;
@@ -252,13 +338,35 @@ 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;
+/** Options belonging only to the built-in CAD UI group. */
+export interface ViewerCadUiOptions {
+    parts?: ViewerCadUiParts;
+    persistence?: boolean;
+    persistenceKey?: string;
+    stateStore?: ViewerCadUiStateStore;
+    keyboard?: ViewerCadUiKeyboardOptions;
+    unitFormatter?: (value: number, context: {
+        readonly unit: string;
+        readonly viewMode: ViewerViewMode;
+    }) => string;
+}
+export interface ViewerCadUiStateStore {
+    read(key: string): string | null;
+    write(key: string, value: string): void;
+}
+export interface ViewerCadUiKeyboardOptions {
+    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 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;
 }