TypeScript Types¶

The @xrgallery/viewer package ships with full TypeScript declarations in dist/index.d.ts. All types are available as ambient globals when the bundle is loaded.

API Types¶

CreateOptions¶

interface CreateOptions {
  element?: string | HTMLElement | null;
  sceneId?: string;
  config?: XRGalleryConfig;
  firebaseConfig?: FirebaseConfig;
  title?: string;
}

ViewerInstance¶

interface ViewerInstance {
  dispose(): void;
  isDisposed(): boolean;
}

FirebaseConfig¶

Only needed if overriding the default XRGallery cloud config.

interface FirebaseConfig {
  apiKey: string;
  authDomain: string;
  projectId: string;
  storageBucket: string;
  messagingSenderId: string;
  appId: string;
  measurementId?: string;
}

Configuration Types¶

XRGalleryConfig¶

Top-level config object passed to create({ config: ... }).

interface XRGalleryConfig {
  experience: ExperienceConfig;
  stages: Stage[];
  navigation?: Navigation;
  globalAudio?: GlobalAudio;
}

ExperienceConfig¶

interface ExperienceConfig {
  title: string;
  description?: string;
  defaultFOV?: number;       // 0.3 - 2.5
}

Stage¶

interface Stage {
  id: string;
  name: string;
  skybox: Skybox;
  hotspots?: Hotspot[];
  models?: Model[];
  planes?: Plane[];
  lights?: Light[];
  audioUrl?: string;
  audioTitle?: string;
  audioVolume?: number;
  initialCameraTarget?: Position3D;
}

Skybox Types¶

type Skybox = ImageSkybox | VideoSkybox | ColorSkybox;

interface ImageSkybox {
  type: 'image';
  url: string;
  rotation?: number;       // degrees
}

interface VideoSkybox {
  type: 'video';
  url?: string;            // MP4
  hlsUrl?: string;         // .m3u8 stream
  thumbnailUrl?: string;
  autoplay?: boolean;
  loop?: boolean;
}

interface ColorSkybox {
  type: 'color';
  color: string;           // hex
}

Hotspot Types¶

type Hotspot =
  | InfoHotspot
  | NavigationHotspot
  | AudioHotspot
  | CombinedHotspot
  | LeadCaptureHotspot;

BaseHotspot¶

All hotspots extend this:

interface BaseHotspot {
  id: string;
  type: string;
  position: Position3D;
  label?: string;
  color?: string;          // hex accent color
}

InfoHotspot¶

interface InfoHotspot extends BaseHotspot {
  type: 'info';
  infoTitle?: string;
  infoDescription?: string;
  infoImageUrl?: string;
  videoUrl?: string;
  linkUrl?: string;
  linkText?: string;
  iframeUrl?: string;
  infoContentType?: 'image' | 'video' | 'iframe';
}

NavigationHotspot¶

interface NavigationHotspot extends BaseHotspot {
  type: 'navigation';
  targetStageId: string;
  portalEffectStyle?: 'clean' | 'enhanced' | 'minimal' | 'alien' | 'floor-arrow';
  portalColor?: string;
  portalRestSize?: number;
  portalHoverSize?: number;
  targetViewDirection?: Position3D;
}

AudioHotspot¶

interface AudioHotspot extends BaseHotspot {
  type: 'audio';
  audioUrl: string;
  audioVolume?: number;      // 0 - 1
  audioLoop?: boolean;
  audioSpatial?: boolean;
  audioRolloffFactor?: number;
  audioMaxDistance?: number;
}

CombinedHotspot¶

interface CombinedHotspot extends BaseHotspot {
  type: 'both';
  infoTitle?: string;
  infoDescription?: string;
  infoImageUrl?: string;
  audioUrl?: string;
}

LeadCaptureHotspot¶

interface LeadCaptureHotspot extends BaseHotspot {
  type: 'lead_capture';
  leadForm?: {
    formType: 'contact' | 'email_capture' | 'inquiry' | 'custom';
    title?: string;
    description?: string;
    submitButtonText?: string;
    fields?: Array<{
      name: string;
      type: 'text' | 'email' | 'textarea' | 'tel' | 'select';
      label: string;
      required?: boolean;
      options?: string[];
    }>;
  };
}

Scene Object Types¶

Model¶

interface Model {
  id?: string;
  url: string;               // glTF/GLB URL
  position?: Position3D;
  rotation?: Position3D;     // radians
  scale?: number | Position3D;
}

Plane¶

interface Plane {
  type: 'image' | 'video';
  url: string;
  hlsUrl?: string;
  position?: Position3D;
  rotation?: Position3D;     // radians
  scale?: { width: number; height: number };
  autoplay?: boolean;
  loop?: boolean;
  muted?: boolean;
}

Light¶

interface Light {
  type: 'hemispheric' | 'point' | 'spot' | 'directional';
  position?: Position3D;
  direction?: Position3D;
  intensity?: number;
  diffuse?: string;          // hex color
  groundColor?: string;      // hemispheric only
  range?: number;            // point/spot
  angle?: number;            // spot only, radians
  exponent?: number;         // spot only
}

Audio Types¶

Stage Audio Fields¶

Per-stage ambient audio is configured directly on each stage:

interface Stage {
  audioUrl?: string;
  audioTitle?: string;
  audioVolume?: number;      // 0 - 1
}

GlobalAudio¶

Background music across all stages.

interface GlobalAudio {
  url: string;
  volume?: number;           // 0 - 1
  loop?: boolean;
}

interface Navigation {
  type: 'floorplan' | 'map' | 'none';
  showMinimap?: boolean;
  floorPlans?: Array<{
    floor: number;
    name: string;
    imageUrl: string;
  }>;
  map?: {
    style: 'streets' | 'satellite' | 'terrain' | 'dark' | 'light';
    defaultZoom?: number;
  };
  markers: Array<{
    stageId: string;
    label?: string;
    floorPlanPosition?: { x: number; y: number };
    geoPosition?: { lat: number; lng: number };
  }>;
}

Utility Types¶

Position3D¶

3D coordinates in meters from the camera center.

interface Position3D {
  x: number;    // Left (-) / Right (+)
  y: number;    // Down (-) / Up (+)
  z: number;    // In front (-) / Behind (+)
}

Window Globals¶

When the IIFE bundle loads, it extends the Window interface:

interface Window {
  XRGallery?: {
    create(options: CreateOptions): Promise<ViewerInstance>;
    init(options: any): Promise<any>;
  };

  /** @deprecated Use XRGallery.create({ config: ... }) instead */
  __XRGALLERY_CONFIG__?: XRGalleryConfig;
}

Using Types in Your Project¶

The types are shipped as ambient declarations. After installing the package, they're available globally:

// No import needed — types are ambient
const options: CreateOptions = {
  element: '#app',
  sceneId: 'abc123'
};

const viewer: ViewerInstance = await XRGallery.create(options);

To reference the config types for validation or type-checking your config objects:

const config: XRGalleryConfig = {
  experience: { title: "My Tour" },
  stages: [
    {
      id: "main",
      name: "Main Hall",
      skybox: { type: "image", url: "/pano.jpg" }
    }
  ]
};