Configuration and Global Settings

/**
 * Get or set the Mapbox access token for API requests
 */
declare const mapboxgl: {
  /**
   * Gets the currently set access token
   * @returns Current access token or undefined if not set
   */
  get accessToken(): string | null | undefined;
  
  /**
   * Sets the access token for Mapbox API requests
   * @param token - Mapbox access token
   */
  set accessToken(token: string);
};

import mapboxgl from 'mapbox-gl';

// Set access token (required for Mapbox services)
mapboxgl.accessToken = 'pk.eyJ1IjoibXl1c2VyIiwiYSI6ImNrZXhhbXBsZSJ9.example';

// Get current access token
const currentToken = mapboxgl.accessToken;
console.log('Current token:', currentToken);

// Set token from environment variable
mapboxgl.accessToken = process.env.MAPBOX_ACCESS_TOKEN;

/**
 * Get or set the base API URL for Mapbox services
 */
declare const mapboxgl: {
  /**
   * Gets the current base API URL
   * @returns Current base API URL
   */
  get baseApiUrl(): string | null | undefined;
  
  /**
   * Sets the base API URL for Mapbox API requests
   * @param url - Base API URL
   */
  set baseApiUrl(url: string);
};

// Use default Mapbox API
mapboxgl.baseApiUrl = 'https://api.mapbox.com';

// Use custom API endpoint
mapboxgl.baseApiUrl = 'https://custom-mapbox-api.example.com';

// Get current API URL
const apiUrl = mapboxgl.baseApiUrl;
console.log('API URL:', apiUrl);

/**
 * Worker thread configuration for map rendering
 */
declare const mapboxgl: {
  /**
   * Gets the current number of web workers
   * @returns Number of web workers
   */
  get workerCount(): number;
  
  /**
   * Sets the number of web workers (must be set before creating maps)
   * @param count - Number of workers to use
   */
  set workerCount(count: number);
  
  /**
   * Gets the current worker URL
   * @returns Worker script URL
   */
  get workerUrl(): string;
  
  /**
   * Sets a custom worker URL for CSP compliance
   * @param url - URL to worker script
   */
  set workerUrl(url: string);
  
  /**
   * Gets the current worker class
   * @returns Worker class constructor
   */
  get workerClass(): Class<Worker>;
  
  /**
   * Sets a custom worker class for bundlers
   * @param klass - Worker class constructor
   */
  set workerClass(klass: Class<Worker>);
  
  /**
   * Gets the current worker parameters
   * @returns Worker options object
   */
  get workerParams(): WorkerOptions;
  
  /**
   * Sets custom worker parameters
   * @param params - Worker options object
   */
  set workerParams(params: WorkerOptions);
};

// Configure worker count (set before creating maps)
mapboxgl.workerCount = 4; // Use 4 workers for better performance

// Custom worker URL for CSP compliance
mapboxgl.workerUrl = 'https://cdn.example.com/mapbox-gl-csp-worker.js';

// Custom worker class for webpack/rollup
import MapboxGLWorker from 'mapbox-gl/dist/mapbox-gl-csp-worker';
mapboxgl.workerClass = MapboxGLWorker;

// Check current settings
console.log(`Using ${mapboxgl.workerCount} workers`);
console.log(`Worker URL: ${mapboxgl.workerUrl}`);

/**
 * Performance-related configuration
 */
declare const mapboxgl: {
  /**
   * Gets the maximum number of parallel image requests
   * @returns Current parallel image request limit
   */
  get maxParallelImageRequests(): number;
  
  /**
   * Sets the maximum number of parallel image requests
   * @param numRequests - Maximum parallel requests
   */
  set maxParallelImageRequests(numRequests: number);
};

// Optimize for high-latency connections
mapboxgl.maxParallelImageRequests = 8;

// Optimize for low-bandwidth connections  
mapboxgl.maxParallelImageRequests = 4;

// Check current setting
console.log(`Max parallel requests: ${mapboxgl.maxParallelImageRequests}`);

/**
 * 3D model and compression configuration
 */
declare const mapboxgl: {
  /**
   * Gets the current Draco decoder URL
   * @returns Draco WASM decoder URL
   */
  get dracoUrl(): string;
  
  /**
   * Sets the Draco decoder URL for 3D model compression
   * @param url - URL to Draco WASM decoder
   */
  set dracoUrl(url: string);
  
  /**
   * Gets the current Meshopt decoder URL
   * @returns Meshopt decoder URL
   */
  get meshoptUrl(): string;
  
  /**
   * Sets the Meshopt decoder URL for 3D optimization
   * @param url - URL to Meshopt decoder
   */
  set meshoptUrl(url: string);
};

// Set Draco decoder for 3D models
mapboxgl.dracoUrl = 'https://cdn.example.com/draco/draco_decoder_gltf.wasm';

// Set Meshopt decoder for optimization  
mapboxgl.meshoptUrl = 'https://cdn.example.com/meshopt/meshopt_decoder.wasm';

// Use Google's CDN for Draco
mapboxgl.dracoUrl = 'https://www.gstatic.com/draco/versioned/decoders/1.5.6/draco_decoder_gltf.wasm';

/**
 * Browser support detection
 * @param options - Support check options
 * @returns True if browser supports Mapbox GL JS
 */
function supported(options?: {
  failIfMajorPerformanceCaveat?: boolean;
}): boolean;

/**
 * Pre-initialize web workers for better performance
 */
function prewarm(): void;

/**
 * Clear pre-initialized resources
 */
function clearPrewarmedResources(): void;

/**
 * Clear tile cache storage
 * @param callback - Callback function called when complete
 */
function clearStorage(callback?: (err?: Error | null) => void): void;

/**
 * Configure RTL text rendering plugin
 * @param pluginURL - URL to RTL text plugin
 * @param callback - Callback function for completion/error
 * @param lazy - Load plugin only when RTL text is encountered
 */
function setRTLTextPlugin(
  pluginURL: string, 
  callback?: (error?: Error) => void, 
  lazy?: boolean
): void;

/**
 * Get RTL text plugin status
 * @returns Plugin status
 */
function getRTLTextPluginStatus(): 'unavailable' | 'loading' | 'loaded' | 'error';

// Check browser support
if (mapboxgl.supported()) {
  console.log('Browser supports Mapbox GL JS');
  initializeMap();
} else {
  console.log('Browser does not support Mapbox GL JS');
  showFallbackMap();
}

// Check support with performance caveat
if (mapboxgl.supported({ failIfMajorPerformanceCaveat: true })) {
  console.log('Browser has good WebGL support');
} else {
  console.log('Browser has limited WebGL support');
}

// Pre-warm workers for better performance
mapboxgl.prewarm();

// Clear resources when done
window.addEventListener('beforeunload', () => {
  mapboxgl.clearPrewarmedResources();
});

// Clear tile cache
mapboxgl.clearStorage((err) => {
  if (err) {
    console.error('Failed to clear storage:', err);
  } else {
    console.log('Storage cleared successfully');
  }
});

// Configure RTL text support
mapboxgl.setRTLTextPlugin(
  'https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-rtl-text/v0.2.3/mapbox-gl-rtl-text.js',
  (error) => {
    if (error) {
      console.error('RTL plugin failed to load:', error);
    } else {
      console.log('RTL plugin loaded successfully');
    }
  },
  true // Lazy load
);

// Check RTL plugin status
const rtlStatus = mapboxgl.getRTLTextPluginStatus();
console.log('RTL plugin status:', rtlStatus);

/**
 * Animation timing control
 */
declare const mapboxgl: {
  /**
   * Override animation timing for video generation
   * @param now - Fixed timestamp for animations
   */
  setNow(now: number): void;
  
  /**
   * Restore normal animation timing
   */
  restoreNow(): void;
};

// Video generation with fixed timing
let frameTime = 0;
const frameRate = 30; // 30 FPS
const frameDuration = 1000 / frameRate;

function generateVideoFrame() {
  mapboxgl.setNow(frameTime);
  
  // Trigger map updates
  map.triggerRepaint();
  
  // Capture frame
  const canvas = map.getCanvasContainer().querySelector('canvas');
  const dataURL = canvas.toDataURL();
  
  frameTime += frameDuration;
}

// Restore normal timing when done
function finishVideoGeneration() {
  mapboxgl.restoreNow();
}

// Testing with controlled timing
function runTimedTest() {
  const startTime = Date.now();
  mapboxgl.setNow(startTime);
  
  // Run test with fixed timing
  performAnimationTest();
  
  // Restore normal timing
  mapboxgl.restoreNow();
}

/**
 * Library version information
 */
declare const mapboxgl: {
  /**
   * Gets the version of Mapbox GL JS
   * @returns Version string (e.g., "3.14.0")
   */
  readonly version: string;
};

// Check library version
console.log(`Mapbox GL JS version: ${mapboxgl.version}`);

// Version-specific feature detection
const [major, minor, patch] = mapboxgl.version.split('.').map(Number);

if (major >= 3) {
  console.log('Using Mapbox GL JS v3+, 3D features available');
  enable3DFeatures();
}

// Display version in UI
document.getElementById('version-info').textContent = `v${mapboxgl.version}`;

// Proper initialization order
import mapboxgl from 'mapbox-gl';

// 1. Set global configuration first
mapboxgl.accessToken = 'your-access-token';
mapboxgl.workerCount = 4;
mapboxgl.maxParallelImageRequests = 8;

// 2. Pre-warm if needed
mapboxgl.prewarm();

// 3. Check support
if (!mapboxgl.supported()) {
  throw new Error('Browser not supported');
}

// 4. Set up RTL if needed
mapboxgl.setRTLTextPlugin('plugin-url');

// 5. Create map
const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v12'
});

// Production vs development configuration
if (process.env.NODE_ENV === 'production') {
  mapboxgl.accessToken = process.env.MAPBOX_PRODUCTION_TOKEN;
  mapboxgl.baseApiUrl = 'https://api.mapbox.com';
  mapboxgl.workerCount = 2;
} else {
  mapboxgl.accessToken = process.env.MAPBOX_DEVELOPMENT_TOKEN;
  mapboxgl.baseApiUrl = 'https://api.mapbox.com';
  mapboxgl.workerCount = 1;
}

// CSP-compliant configuration
if (process.env.CSP_MODE === 'strict') {
  mapboxgl.workerUrl = '/static/mapbox-gl-csp-worker.js';
  mapboxgl.dracoUrl = '/static/draco_decoder_gltf.wasm';
}

// Configuration-related types
interface Class<T> {
  new (...args: any[]): T;
}

type PluginStatus = 'unavailable' | 'loading' | 'loaded' | 'error';

// Worker configuration options
interface WorkerOptions {
  type?: 'classic' | 'module';
  credentials?: 'omit' | 'same-origin' | 'include';
  name?: string;
}

// Global configuration object type
interface MapboxGL {
  // Properties
  readonly version: string;
  accessToken: string;
  baseApiUrl: string;
  workerCount: number;
  workerUrl: string;
  workerClass: Class<Worker>;
  workerParams: WorkerOptions;
  maxParallelImageRequests: number;
  dracoUrl: string;
  meshoptUrl: string;
  
  // Functions
  supported(options?: { failIfMajorPerformanceCaveat?: boolean }): boolean;
  prewarm(): void;
  clearPrewarmedResources(): void;
  clearStorage(callback?: (err?: Error | null) => void): void;
  setRTLTextPlugin(pluginURL: string, callback?: (error?: Error) => void, lazy?: boolean): void;
  getRTLTextPluginStatus(): PluginStatus;
  setNow(now: number): void;
  restoreNow(): void;
}