Hybrid Navigation System¶

// ============================================================================
// NAVIGATION TYPES
// ============================================================================

/**
 * Geographic coordinates (latitude/longitude)
 */
export interface GeoCoordinates {
  lat: number;   // Latitude (-90 to 90)
  lng: number;   // Longitude (-180 to 180)
}

/**
 * 2D position on a floor plan image (percentage-based)
 */
export interface FloorPlanPosition {
  x: number;     // 0-1 (0 = left edge, 1 = right edge)
  y: number;     // 0-1 (0 = top edge, 1 = bottom edge)
}

/**
 * A marker/pin on the navigation overlay
 */
export interface NavigationMarker {
  stageId: string;              // Links to ExperienceStage.id
  label?: string;               // Override stage name for marker label

  // Position (one of these is required based on navigation type)
  floorPlanPosition?: FloorPlanPosition;  // For floor plans
  geoPosition?: GeoCoordinates;            // For maps

  // Optional customization
  icon?: 'default' | 'star' | 'info' | 'camera' | 'video' | 'audio' | 'custom';
  customIconUrl?: string;       // URL to custom marker icon
  color?: string;               // Marker color (hex)
  initialViewDirection?: number; // Camera direction when entering (degrees, 0 = north)
}

/**
 * Floor plan configuration
 */
export interface FloorPlanConfig {
  imageUrl: string;             // PNG, JPG, or SVG of floor plan

  // Optional: Real-world dimensions (for scale reference)
  realWorldWidth?: number;      // Width in meters
  realWorldHeight?: number;     // Height in meters

  // Multi-floor support
  floor?: number;               // Floor number (for multi-floor buildings)
  floorLabel?: string;          // "Ground Floor", "Level 2", etc.
}

/**
 * Interactive map configuration
 */
export interface MapConfig {
  style: 'streets' | 'satellite' | 'terrain' | 'dark' | 'light';

  // Map bounds (optional - auto-fits to markers if not specified)
  bounds?: {
    north: number;  // Max latitude
    south: number;  // Min latitude
    east: number;   // Max longitude
    west: number;   // Min longitude
  };

  // Default view
  defaultCenter?: GeoCoordinates;
  defaultZoom?: number;         // 1-20 (1 = world, 20 = building)

  // Clustering for many markers
  enableClustering?: boolean;   // Group nearby markers at low zoom
  clusterRadius?: number;       // Pixels (default: 50)
}

/**
 * Complete navigation configuration
 */
export interface NavigationConfig {
  type: 'floorplan' | 'map' | 'none';

  // Display settings
  displayMode: 'minimap' | 'fullscreen' | 'both';
  minimapPosition?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
  minimapSize?: 'small' | 'medium' | 'large'; // 150px, 200px, 250px

  // Floor plan (when type = 'floorplan')
  floorPlan?: FloorPlanConfig;
  floorPlans?: FloorPlanConfig[];  // Multi-floor support

  // Map (when type = 'map')
  map?: MapConfig;

  // Markers (shared for both types)
  markers: NavigationMarker[];

  // VR settings
  vrDisplay?: 'floating-panel' | 'wrist-mounted' | 'hidden';
}

export interface ExperienceConfig {
  experience: {
    title: string;
    description?: string;
  };
  stages: ExperienceStage[];
  navigation?: NavigationConfig;  // NEW: Optional navigation overlay
}

export interface ExperienceStage {
  id: string;
  name?: string;
  skybox?: SkyboxConfig;
  models?: ModelConfig[];
  planes?: PlaneConfig[];
  audioUrl?: string;
  audioTitle?: string;
  lights?: LightConfig[];
  hotspots?: HotspotConfig[];

  // NEW: Geographic location (for map-based navigation)
  location?: GeoCoordinates;
}

// src/ui/NavigationOverlay.ts

export interface NavigationOverlayEvents {
  onMarkerClick: (stageId: string) => void;
  onMarkerHover: (stageId: string | null) => void;
  onExpandToggle: (isExpanded: boolean) => void;
}

export abstract class NavigationOverlay {
  protected container: HTMLElement;
  protected config: NavigationConfig;
  protected currentStageId: string | null = null;
  protected events: NavigationOverlayEvents;

  constructor(
    container: HTMLElement,
    config: NavigationConfig,
    events: NavigationOverlayEvents
  ) {
    this.container = container;
    this.config = config;
    this.events = events;
  }

  abstract render(): void;
  abstract updateCurrentStage(stageId: string): void;
  abstract setExpanded(expanded: boolean): void;
  abstract dispose(): void;

  // For VR mode
  abstract createVRPanel(): Mesh | null;
}

// src/ui/FloorPlanOverlay.ts

import { NavigationOverlay, NavigationOverlayEvents } from './NavigationOverlay';
import type { NavigationConfig, NavigationMarker, FloorPlanConfig } from '../types/config';

export class FloorPlanOverlay extends NavigationOverlay {
  private minimapContainer: HTMLElement | null = null;
  private fullscreenContainer: HTMLElement | null = null;
  private currentFloorIndex: number = 0;
  private isExpanded: boolean = false;

  render(): void {
    this.createMinimapView();
    if (this.config.displayMode === 'both' || this.config.displayMode === 'fullscreen') {
      this.createFullscreenView();
    }
    this.renderMarkers();
    this.setupEventListeners();
  }

  private createMinimapView(): void {
    const position = this.config.minimapPosition || 'bottom-left';
    const size = this.config.minimapSize || 'medium';

    this.minimapContainer = document.createElement('div');
    this.minimapContainer.className = `floor-plan-minimap floor-plan-${position} floor-plan-${size}`;
    this.minimapContainer.innerHTML = `
      <div class="floor-plan-image-container">
        <img src="${this.getFloorPlanUrl()}" alt="Floor Plan" />
        <svg class="floor-plan-markers"></svg>
      </div>
      <button class="floor-plan-expand-btn" aria-label="Expand">
        <svg viewBox="0 0 24 24" width="16" height="16">
          <path fill="currentColor" d="M7 14H5v5h5v-2H7v-3zm-2-4h2V7h3V5H5v5zm12 7h-3v2h5v-5h-2v3zM14 5v2h3v3h2V5h-5z"/>
        </svg>
      </button>
    `;
    this.container.appendChild(this.minimapContainer);
  }

  private renderMarkers(): void {
    const svg = this.minimapContainer?.querySelector('.floor-plan-markers');
    if (!svg) return;

    svg.innerHTML = '';

    this.config.markers.forEach(marker => {
      if (!marker.floorPlanPosition) return;

      const circle = document.createElementNS('http://www.w3.org/2000/svg', 'circle');
      circle.setAttribute('cx', `${marker.floorPlanPosition.x * 100}%`);
      circle.setAttribute('cy', `${marker.floorPlanPosition.y * 100}%`);
      circle.setAttribute('r', marker.stageId === this.currentStageId ? '10' : '6');
      circle.setAttribute('class', `marker ${marker.stageId === this.currentStageId ? 'current' : ''}`);
      circle.setAttribute('data-stage-id', marker.stageId);

      if (marker.color) {
        circle.style.fill = marker.color;
      }

      // Click handler
      circle.addEventListener('click', (e) => {
        e.stopPropagation();
        this.events.onMarkerClick(marker.stageId);
      });

      // Hover handler
      circle.addEventListener('mouseenter', () => {
        this.events.onMarkerHover(marker.stageId);
        this.showTooltip(marker);
      });

      circle.addEventListener('mouseleave', () => {
        this.events.onMarkerHover(null);
        this.hideTooltip();
      });

      svg.appendChild(circle);
    });
  }

  updateCurrentStage(stageId: string): void {
    this.currentStageId = stageId;
    this.renderMarkers(); // Re-render with new current marker
  }

  setExpanded(expanded: boolean): void {
    this.isExpanded = expanded;
    if (this.minimapContainer) {
      this.minimapContainer.hidden = expanded;
    }
    if (this.fullscreenContainer) {
      this.fullscreenContainer.hidden = !expanded;
    }
    this.events.onExpandToggle(expanded);
  }

  private getFloorPlanUrl(): string {
    if (this.config.floorPlans && this.config.floorPlans.length > 0) {
      return this.config.floorPlans[this.currentFloorIndex].imageUrl;
    }
    return this.config.floorPlan?.imageUrl || '';
  }

  dispose(): void {
    this.minimapContainer?.remove();
    this.fullscreenContainer?.remove();
  }

  createVRPanel(): Mesh | null {
    // Create Babylon.js plane with floor plan texture
    // Implementation similar to existing VR GUI panels
    return null; // TODO: Implement VR version
  }
}

// src/ui/MapOverlay.ts

import mapboxgl from 'mapbox-gl';
import { NavigationOverlay, NavigationOverlayEvents } from './NavigationOverlay';
import type { NavigationConfig, NavigationMarker } from '../types/config';

// Set your Mapbox access token (or use env variable)
mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_TOKEN || '';

export class MapOverlay extends NavigationOverlay {
  private map: mapboxgl.Map | null = null;
  private markers: Map<string, mapboxgl.Marker> = new Map();
  private minimapContainer: HTMLElement | null = null;

  render(): void {
    this.createMapContainer();
    this.initializeMap();
    this.addMarkers();
  }

  private createMapContainer(): void {
    const position = this.config.minimapPosition || 'bottom-left';

    this.minimapContainer = document.createElement('div');
    this.minimapContainer.className = `map-overlay map-${position}`;
    this.minimapContainer.innerHTML = `
      <div class="map-container" id="navigation-map"></div>
      <button class="map-expand-btn" aria-label="Expand map">
        <svg viewBox="0 0 24 24" width="16" height="16">
          <path fill="currentColor" d="M7 14H5v5h5v-2H7v-3zm-2-4h2V7h3V5H5v5zm12 7h-3v2h5v-5h-2v3zM14 5v2h3v3h2V5h-5z"/>
        </svg>
      </button>
    `;
    this.container.appendChild(this.minimapContainer);
  }

  private initializeMap(): void {
    const mapConfig = this.config.map;
    if (!mapConfig) return;

    const styleMap: Record<string, string> = {
      streets: 'mapbox://styles/mapbox/streets-v12',
      satellite: 'mapbox://styles/mapbox/satellite-streets-v12',
      terrain: 'mapbox://styles/mapbox/outdoors-v12',
      dark: 'mapbox://styles/mapbox/dark-v11',
      light: 'mapbox://styles/mapbox/light-v11',
    };

    this.map = new mapboxgl.Map({
      container: 'navigation-map',
      style: styleMap[mapConfig.style] || styleMap.terrain,
      center: mapConfig.defaultCenter
        ? [mapConfig.defaultCenter.lng, mapConfig.defaultCenter.lat]
        : [-98.5, 39.8], // Center of USA
      zoom: mapConfig.defaultZoom || 4,
      attributionControl: false,
    });

    // Fit bounds if specified
    if (mapConfig.bounds) {
      this.map.fitBounds([
        [mapConfig.bounds.west, mapConfig.bounds.south],
        [mapConfig.bounds.east, mapConfig.bounds.north],
      ], { padding: 50 });
    }

    // Auto-fit to markers if no bounds specified
    else if (this.config.markers.length > 0) {
      this.fitToMarkers();
    }
  }

  private addMarkers(): void {
    if (!this.map) return;

    this.config.markers.forEach(marker => {
      if (!marker.geoPosition) return;

      // Create marker element
      const el = document.createElement('div');
      el.className = `map-marker ${marker.stageId === this.currentStageId ? 'current' : ''}`;
      el.style.backgroundColor = marker.color || '#4A90E2';
      el.setAttribute('data-stage-id', marker.stageId);

      // Add icon if specified
      if (marker.icon && marker.icon !== 'default') {
        el.innerHTML = this.getMarkerIcon(marker.icon);
      }

      // Create Mapbox marker
      const mapboxMarker = new mapboxgl.Marker({ element: el })
        .setLngLat([marker.geoPosition.lng, marker.geoPosition.lat])
        .addTo(this.map!);

      // Add popup
      const popup = new mapboxgl.Popup({ offset: 25, closeButton: false })
        .setText(marker.label || marker.stageId);

      mapboxMarker.setPopup(popup);

      // Click handler
      el.addEventListener('click', () => {
        this.events.onMarkerClick(marker.stageId);
      });

      this.markers.set(marker.stageId, mapboxMarker);
    });
  }

  private fitToMarkers(): void {
    if (!this.map || this.config.markers.length === 0) return;

    const bounds = new mapboxgl.LngLatBounds();

    this.config.markers.forEach(marker => {
      if (marker.geoPosition) {
        bounds.extend([marker.geoPosition.lng, marker.geoPosition.lat]);
      }
    });

    this.map.fitBounds(bounds, { padding: 50, maxZoom: 15 });
  }

  updateCurrentStage(stageId: string): void {
    // Update previous current marker
    if (this.currentStageId) {
      const prevMarker = this.markers.get(this.currentStageId);
      prevMarker?.getElement()?.classList.remove('current');
    }

    // Update new current marker
    this.currentStageId = stageId;
    const currentMarker = this.markers.get(stageId);
    currentMarker?.getElement()?.classList.add('current');

    // Center map on current marker
    const markerConfig = this.config.markers.find(m => m.stageId === stageId);
    if (markerConfig?.geoPosition && this.map) {
      this.map.flyTo({
        center: [markerConfig.geoPosition.lng, markerConfig.geoPosition.lat],
        zoom: Math.max(this.map.getZoom(), 8),
        duration: 1000,
      });
    }
  }

  private getMarkerIcon(icon: string): string {
    const icons: Record<string, string> = {
      star: '★',
      camera: '📷',
      video: '🎬',
      audio: '🔊',
      info: 'ℹ',
    };
    return icons[icon] || '';
  }

  setExpanded(expanded: boolean): void {
    // Toggle fullscreen map view
  }

  dispose(): void {
    this.map?.remove();
    this.minimapContainer?.remove();
  }

  createVRPanel(): Mesh | null {
    // For VR: render map as a static texture on a plane
    // (Interactive maps in VR are complex - static snapshot is simpler)
    return null;
  }
}