@maplibre-yaml/core 0.1.0-alpha.0

package/dist/components/index.js

@@ -0,0 +1,4332 @@
+import maplibregl2 from 'maplibre-gl';
+import { parse } from 'yaml';
+import { z, ZodError } from 'zod';
+
+// @maplibre-yaml/core - Declarative web maps with YAML
+
+
+// src/data/memory-cache.ts
+var MemoryCache = class _MemoryCache {
+  static DEFAULT_CONFIG = {
+    maxSize: 100,
+    defaultTTL: 3e5,
+    // 5 minutes
+    useConditionalRequests: true
+  };
+  config;
+  cache = /* @__PURE__ */ new Map();
+  accessOrder = [];
+  stats = { hits: 0, misses: 0 };
+  /**
+   * Create a new MemoryCache instance
+   *
+   * @param config - Cache configuration options
+   */
+  constructor(config) {
+    this.config = { ..._MemoryCache.DEFAULT_CONFIG, ...config };
+  }
+  /**
+   * Retrieve a cache entry
+   *
+   * @remarks
+   * - Returns null if key doesn't exist
+   * - Returns null if entry has expired (and removes it)
+   * - Updates access order for LRU
+   * - Updates cache statistics
+   *
+   * @param key - Cache key (typically a URL)
+   * @returns Cache entry or null if not found/expired
+   */
+  get(key) {
+    const entry = this.cache.get(key);
+    if (!entry) {
+      this.stats.misses++;
+      return null;
+    }
+    const ttl = entry.ttl ?? this.config.defaultTTL;
+    const age = Date.now() - entry.timestamp;
+    if (age > ttl) {
+      this.cache.delete(key);
+      this.removeFromAccessOrder(key);
+      this.stats.misses++;
+      return null;
+    }
+    this.updateAccessOrder(key);
+    this.stats.hits++;
+    return entry;
+  }
+  /**
+   * Check if a key exists in cache (without checking expiration)
+   *
+   * @param key - Cache key
+   * @returns True if key exists in cache
+   */
+  has(key) {
+    return this.cache.has(key);
+  }
+  /**
+   * Store a cache entry
+   *
+   * @remarks
+   * - Evicts least recently used entries if at capacity
+   * - Updates access order
+   *
+   * @param key - Cache key (typically a URL)
+   * @param entry - Cache entry to store
+   */
+  set(key, entry) {
+    while (this.cache.size >= this.config.maxSize && !this.cache.has(key)) {
+      const oldest = this.accessOrder.shift();
+      if (oldest) {
+        this.cache.delete(oldest);
+      }
+    }
+    this.cache.set(key, entry);
+    this.updateAccessOrder(key);
+  }
+  /**
+   * Delete a cache entry
+   *
+   * @param key - Cache key
+   * @returns True if entry was deleted, false if it didn't exist
+   */
+  delete(key) {
+    const existed = this.cache.delete(key);
+    if (existed) {
+      this.removeFromAccessOrder(key);
+    }
+    return existed;
+  }
+  /**
+   * Clear all cache entries and reset statistics
+   */
+  clear() {
+    this.cache.clear();
+    this.accessOrder = [];
+    this.stats = { hits: 0, misses: 0 };
+  }
+  /**
+   * Remove expired entries from cache
+   *
+   * @remarks
+   * Iterates through all entries and removes those that have exceeded their TTL.
+   * This is useful for periodic cleanup.
+   *
+   * @returns Number of entries removed
+   */
+  prune() {
+    let removed = 0;
+    const now = Date.now();
+    for (const [key, entry] of this.cache.entries()) {
+      const ttl = entry.ttl ?? this.config.defaultTTL;
+      const age = now - entry.timestamp;
+      if (age > ttl) {
+        this.cache.delete(key);
+        this.removeFromAccessOrder(key);
+        removed++;
+      }
+    }
+    return removed;
+  }
+  /**
+   * Get cache statistics
+   *
+   * @returns Current cache statistics including hit rate
+   */
+  getStats() {
+    const total = this.stats.hits + this.stats.misses;
+    const hitRate = total > 0 ? this.stats.hits / total * 100 : 0;
+    return {
+      size: this.cache.size,
+      hits: this.stats.hits,
+      misses: this.stats.misses,
+      hitRate: Math.round(hitRate * 100) / 100
+      // Round to 2 decimal places
+    };
+  }
+  /**
+   * Get conditional request headers for HTTP caching
+   *
+   * @remarks
+   * Returns appropriate If-None-Match and/or If-Modified-Since headers
+   * based on cached entry metadata. Returns empty object if:
+   * - Key doesn't exist in cache
+   * - Entry has expired
+   * - useConditionalRequests is false
+   *
+   * @param key - Cache key
+   * @returns Object with conditional headers (may be empty)
+   *
+   * @example
+   * ```typescript
+   * const headers = cache.getConditionalHeaders(url);
+   * const response = await fetch(url, { headers });
+   * if (response.status === 304) {
+   *   // Use cached data
+   * }
+   * ```
+   */
+  getConditionalHeaders(key) {
+    if (!this.config.useConditionalRequests) {
+      return {};
+    }
+    const entry = this.get(key);
+    if (!entry) {
+      return {};
+    }
+    const headers = {};
+    if (entry.etag) {
+      headers["If-None-Match"] = entry.etag;
+    }
+    if (entry.lastModified) {
+      headers["If-Modified-Since"] = entry.lastModified;
+    }
+    return headers;
+  }
+  /**
+   * Update the last access time for an entry
+   *
+   * @remarks
+   * Useful for keeping an entry "fresh" without modifying its data.
+   * Updates the access order for LRU.
+   *
+   * @param key - Cache key
+   */
+  touch(key) {
+    if (this.cache.has(key)) {
+      this.updateAccessOrder(key);
+    }
+  }
+  /**
+   * Update access order for LRU tracking
+   *
+   * @param key - Cache key
+   */
+  updateAccessOrder(key) {
+    this.removeFromAccessOrder(key);
+    this.accessOrder.push(key);
+  }
+  /**
+   * Remove a key from access order array
+   *
+   * @param key - Cache key
+   */
+  removeFromAccessOrder(key) {
+    const index = this.accessOrder.indexOf(key);
+    if (index !== -1) {
+      this.accessOrder.splice(index, 1);
+    }
+  }
+};
+
+// src/data/retry-manager.ts
+var MaxRetriesExceededError = class _MaxRetriesExceededError extends Error {
+  /**
+   * Create a MaxRetriesExceededError
+   *
+   * @param lastError - The error from the final attempt
+   * @param attempts - Number of attempts made
+   */
+  constructor(lastError, attempts) {
+    super(
+      `Maximum retry attempts (${attempts}) exceeded. Last error: ${lastError.message}`
+    );
+    this.lastError = lastError;
+    this.attempts = attempts;
+    this.name = "MaxRetriesExceededError";
+    Object.setPrototypeOf(this, _MaxRetriesExceededError.prototype);
+  }
+};
+var RetryManager = class _RetryManager {
+  static DEFAULT_CONFIG = {
+    maxRetries: 10,
+    initialDelay: 1e3,
+    maxDelay: 3e4,
+    backoffFactor: 2,
+    jitter: true,
+    jitterFactor: 0.25
+  };
+  config;
+  /**
+   * Create a new RetryManager instance
+   *
+   * @param config - Retry configuration options
+   */
+  constructor(config) {
+    this.config = { ..._RetryManager.DEFAULT_CONFIG, ...config };
+  }
+  /**
+   * Execute a function with retry logic
+   *
+   * @typeParam T - Return type of the function
+   * @param fn - Async function to execute with retries
+   * @param callbacks - Optional lifecycle callbacks
+   * @returns Promise that resolves with the function's result
+   * @throws {MaxRetriesExceededError} When all retry attempts fail
+   *
+   * @example
+   * ```typescript
+   * const data = await retry.execute(
+   *   () => fetchData(url),
+   *   {
+   *     isRetryable: (error) => {
+   *       // Don't retry 4xx errors except 429 (rate limit)
+   *       if (error.message.includes('429')) return true;
+   *       if (error.message.match(/4\d\d/)) return false;
+   *       return true;
+   *     },
+   *   }
+   * );
+   * ```
+   */
+  async execute(fn, callbacks) {
+    let lastError = null;
+    let attempt = 0;
+    while (attempt <= this.config.maxRetries) {
+      attempt++;
+      try {
+        const result = await fn();
+        callbacks?.onSuccess?.(attempt);
+        return result;
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (callbacks?.isRetryable && !callbacks.isRetryable(lastError)) {
+          throw lastError;
+        }
+        if (attempt > this.config.maxRetries) {
+          callbacks?.onExhausted?.(attempt, lastError);
+          throw new MaxRetriesExceededError(lastError, attempt);
+        }
+        const delay = this.calculateDelay(attempt);
+        callbacks?.onRetry?.(attempt, delay, lastError);
+        await this.sleep(delay);
+      }
+    }
+    throw new MaxRetriesExceededError(
+      lastError || new Error("Unknown error"),
+      attempt
+    );
+  }
+  /**
+   * Calculate delay for a given attempt using exponential backoff
+   *
+   * @param attempt - Current attempt number (1-indexed)
+   * @returns Delay in milliseconds
+   *
+   * @example
+   * ```typescript
+   * const retry = new RetryManager({ initialDelay: 1000, backoffFactor: 2 });
+   * console.log(retry.calculateDelay(1)); // ~1000ms
+   * console.log(retry.calculateDelay(2)); // ~2000ms
+   * console.log(retry.calculateDelay(3)); // ~4000ms
+   * ```
+   */
+  calculateDelay(attempt) {
+    let delay = this.config.initialDelay * Math.pow(this.config.backoffFactor, attempt - 1);
+    delay = Math.min(delay, this.config.maxDelay);
+    if (this.config.jitter) {
+      const jitterRange = delay * this.config.jitterFactor;
+      const jitterOffset = (Math.random() * 2 - 1) * jitterRange;
+      delay = delay + jitterOffset;
+    }
+    return Math.max(0, Math.round(delay));
+  }
+  /**
+   * Reset internal state
+   *
+   * @remarks
+   * Currently this class is stateless, but this method is provided
+   * for API consistency and future extensibility.
+   */
+  reset() {
+  }
+  /**
+   * Sleep for specified milliseconds
+   *
+   * @param ms - Milliseconds to sleep
+   * @returns Promise that resolves after the delay
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/data/data-fetcher.ts
+var DataFetcher = class _DataFetcher {
+  static DEFAULT_CONFIG = {
+    cache: {
+      enabled: true,
+      defaultTTL: 3e5,
+      // 5 minutes
+      maxSize: 100
+    },
+    retry: {
+      enabled: true,
+      maxRetries: 3,
+      initialDelay: 1e3,
+      maxDelay: 1e4
+    },
+    timeout: 3e4,
+    defaultHeaders: {
+      Accept: "application/geo+json,application/json"
+    }
+  };
+  config;
+  cache;
+  retryManager;
+  activeRequests = /* @__PURE__ */ new Map();
+  /**
+   * Create a new DataFetcher instance
+   *
+   * @param config - Fetcher configuration
+   */
+  constructor(config) {
+    this.config = this.mergeConfig(config);
+    this.cache = new MemoryCache({
+      maxSize: this.config.cache.maxSize,
+      defaultTTL: this.config.cache.defaultTTL,
+      useConditionalRequests: true
+    });
+    this.retryManager = new RetryManager({
+      maxRetries: this.config.retry.maxRetries,
+      initialDelay: this.config.retry.initialDelay,
+      maxDelay: this.config.retry.maxDelay
+    });
+  }
+  /**
+   * Fetch GeoJSON data from a URL
+   *
+   * @param url - URL to fetch from
+   * @param options - Fetch options
+   * @returns Fetch result with data and metadata
+   * @throws {Error} On network error, timeout, invalid JSON, or non-GeoJSON response
+   *
+   * @example
+   * ```typescript
+   * const result = await fetcher.fetch(
+   *   'https://example.com/data.geojson',
+   *   {
+   *     ttl: 60000, // 1 minute cache
+   *     onRetry: (attempt, delay, error) => {
+   *       console.log(`Retry ${attempt} in ${delay}ms: ${error.message}`);
+   *     },
+   *   }
+   * );
+   * ```
+   */
+  async fetch(url, options = {}) {
+    const startTime = Date.now();
+    options.onStart?.();
+    try {
+      if (this.config.cache.enabled && !options.skipCache) {
+        const cached = this.cache.get(url);
+        if (cached) {
+          const result2 = {
+            data: cached.data,
+            fromCache: true,
+            featureCount: cached.data.features.length,
+            duration: Date.now() - startTime
+          };
+          options.onComplete?.(cached.data, true);
+          return result2;
+        }
+      }
+      const data = await this.fetchWithRetry(url, options);
+      if (this.config.cache.enabled && !options.skipCache) {
+        const cacheEntry = {
+          data,
+          timestamp: Date.now(),
+          ttl: options.ttl
+        };
+        this.cache.set(url, cacheEntry);
+      }
+      const result = {
+        data,
+        fromCache: false,
+        featureCount: data.features.length,
+        duration: Date.now() - startTime
+      };
+      options.onComplete?.(data, false);
+      return result;
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      options.onError?.(err);
+      throw err;
+    }
+  }
+  /**
+   * Prefetch data and store in cache
+   *
+   * @remarks
+   * Useful for preloading data that will be needed soon.
+   * Does not return the data.
+   *
+   * @param url - URL to prefetch
+   * @param ttl - Optional custom TTL for cached entry
+   *
+   * @example
+   * ```typescript
+   * // Prefetch data for quick access later
+   * await fetcher.prefetch('https://example.com/data.geojson', 600000);
+   * ```
+   */
+  async prefetch(url, ttl) {
+    await this.fetch(url, { ttl, skipCache: false });
+  }
+  /**
+   * Invalidate cached entry for a URL
+   *
+   * @param url - URL to invalidate
+   *
+   * @example
+   * ```typescript
+   * // Force next fetch to get fresh data
+   * fetcher.invalidate('https://example.com/data.geojson');
+   * ```
+   */
+  invalidate(url) {
+    this.cache.delete(url);
+  }
+  /**
+   * Clear all cached entries
+   */
+  clearCache() {
+    this.cache.clear();
+  }
+  /**
+   * Get cache statistics
+   *
+   * @returns Cache stats including size, hits, misses, and hit rate
+   */
+  getCacheStats() {
+    return this.cache.getStats();
+  }
+  /**
+   * Abort all active requests
+   */
+  abortAll() {
+    for (const controller of this.activeRequests.values()) {
+      controller.abort();
+    }
+    this.activeRequests.clear();
+  }
+  /**
+   * Fetch with retry logic
+   */
+  async fetchWithRetry(url, options) {
+    if (!this.config.retry.enabled) {
+      return this.performFetch(url, options);
+    }
+    return this.retryManager.execute(
+      () => this.performFetch(url, options),
+      {
+        onRetry: options.onRetry,
+        isRetryable: (error) => this.isRetryableError(error)
+      }
+    );
+  }
+  /**
+   * Perform the actual HTTP fetch
+   */
+  async performFetch(url, options) {
+    const controller = options.signal ? new AbortController() : new AbortController();
+    if (options.signal) {
+      options.signal.addEventListener("abort", () => controller.abort());
+    }
+    const timeoutId = setTimeout(() => {
+      controller.abort();
+    }, this.config.timeout);
+    this.activeRequests.set(url, controller);
+    try {
+      const headers = {
+        ...this.config.defaultHeaders,
+        ...options.headers
+      };
+      if (this.config.cache.enabled && this.cache.has(url)) {
+        const conditionalHeaders = this.cache.getConditionalHeaders(url);
+        Object.assign(headers, conditionalHeaders);
+      }
+      const response = await fetch(url, {
+        signal: controller.signal,
+        headers
+      });
+      if (response.status === 304) {
+        const cached = this.cache.get(url);
+        if (cached) {
+          this.cache.touch(url);
+          return cached.data;
+        }
+        throw new Error("304 Not Modified but no cached data available");
+      }
+      if (!response.ok) {
+        throw new Error(
+          `HTTP ${response.status}: ${response.statusText} for ${url}`
+        );
+      }
+      let data;
+      try {
+        data = await response.json();
+      } catch (error) {
+        throw new Error(`Invalid JSON response from ${url}`);
+      }
+      if (!this.isValidGeoJSON(data)) {
+        throw new Error(`Response from ${url} is not valid GeoJSON`);
+      }
+      if (this.config.cache.enabled) {
+        const etag = response.headers.get("etag");
+        const lastModified = response.headers.get("last-modified");
+        if (etag || lastModified) {
+          const cached = this.cache.get(url);
+          if (cached) {
+            this.cache.set(url, {
+              ...cached,
+              etag: etag || cached.etag,
+              lastModified: lastModified || cached.lastModified
+            });
+          }
+        }
+      }
+      return data;
+    } finally {
+      clearTimeout(timeoutId);
+      this.activeRequests.delete(url);
+    }
+  }
+  /**
+   * Check if an error should trigger a retry
+   */
+  isRetryableError(error) {
+    const message = error.message.toLowerCase();
+    if (message.includes("http 4") && !message.includes("429")) {
+      return false;
+    }
+    if (message.includes("invalid json") || message.includes("not valid geojson")) {
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Validate that data is a GeoJSON FeatureCollection
+   */
+  isValidGeoJSON(data) {
+    if (typeof data !== "object" || data === null) {
+      return false;
+    }
+    const obj = data;
+    return obj.type === "FeatureCollection" && Array.isArray(obj.features);
+  }
+  /**
+   * Merge partial config with defaults
+   */
+  mergeConfig(partial) {
+    if (!partial) return _DataFetcher.DEFAULT_CONFIG;
+    return {
+      cache: { ..._DataFetcher.DEFAULT_CONFIG.cache, ...partial.cache },
+      retry: { ..._DataFetcher.DEFAULT_CONFIG.retry, ...partial.retry },
+      timeout: partial.timeout ?? _DataFetcher.DEFAULT_CONFIG.timeout,
+      defaultHeaders: {
+        ..._DataFetcher.DEFAULT_CONFIG.defaultHeaders,
+        ...partial.defaultHeaders
+      }
+    };
+  }
+};
+
+// src/data/polling-manager.ts
+var PollingManager = class {
+  subscriptions = /* @__PURE__ */ new Map();
+  visibilityListener = null;
+  constructor() {
+    this.setupVisibilityListener();
+  }
+  /**
+   * Start a new polling subscription.
+   *
+   * @param id - Unique identifier for the subscription
+   * @param config - Polling configuration
+   * @throws Error if a subscription with the same ID already exists
+   *
+   * @example
+   * ```typescript
+   * polling.start('layer-1', {
+   *   interval: 5000,
+   *   onTick: async () => {
+   *     await updateLayerData();
+   *   },
+   * });
+   * ```
+   */
+  start(id, config) {
+    if (this.subscriptions.has(id)) {
+      throw new Error(`Polling subscription with id "${id}" already exists`);
+    }
+    const subscription = {
+      config,
+      state: {
+        isActive: true,
+        isPaused: false,
+        lastTick: null,
+        nextTick: null,
+        tickCount: 0,
+        errorCount: 0
+      },
+      timerId: null,
+      isExecuting: false,
+      pausedByVisibility: false
+    };
+    this.subscriptions.set(id, subscription);
+    if (config.immediate) {
+      this.executeTick(id);
+    } else {
+      this.scheduleNextTick(id);
+    }
+  }
+  /**
+   * Stop a polling subscription and clean up resources.
+   *
+   * @param id - Subscription identifier
+   *
+   * @example
+   * ```typescript
+   * polling.stop('layer-1');
+   * ```
+   */
+  stop(id) {
+    const subscription = this.subscriptions.get(id);
+    if (!subscription) return;
+    if (subscription.timerId !== null) {
+      clearTimeout(subscription.timerId);
+    }
+    subscription.state.isActive = false;
+    this.subscriptions.delete(id);
+  }
+  /**
+   * Stop all polling subscriptions.
+   *
+   * @example
+   * ```typescript
+   * polling.stopAll();
+   * ```
+   */
+  stopAll() {
+    for (const id of this.subscriptions.keys()) {
+      this.stop(id);
+    }
+  }
+  /**
+   * Pause a polling subscription without stopping it.
+   *
+   * @param id - Subscription identifier
+   *
+   * @remarks
+   * Paused subscriptions can be resumed with {@link resume}.
+   * The subscription maintains its state while paused.
+   *
+   * @example
+   * ```typescript
+   * polling.pause('layer-1');
+   * ```
+   */
+  pause(id) {
+    const subscription = this.subscriptions.get(id);
+    if (!subscription || subscription.state.isPaused) return;
+    if (subscription.timerId !== null) {
+      clearTimeout(subscription.timerId);
+      subscription.timerId = null;
+    }
+    subscription.state.isPaused = true;
+    subscription.state.nextTick = null;
+  }
+  /**
+   * Pause all active polling subscriptions.
+   *
+   * @example
+   * ```typescript
+   * polling.pauseAll();
+   * ```
+   */
+  pauseAll() {
+    for (const id of this.subscriptions.keys()) {
+      this.pause(id);
+    }
+  }
+  /**
+   * Resume a paused polling subscription.
+   *
+   * @param id - Subscription identifier
+   *
+   * @example
+   * ```typescript
+   * polling.resume('layer-1');
+   * ```
+   */
+  resume(id) {
+    const subscription = this.subscriptions.get(id);
+    if (!subscription || !subscription.state.isPaused) return;
+    subscription.state.isPaused = false;
+    subscription.pausedByVisibility = false;
+    this.scheduleNextTick(id);
+  }
+  /**
+   * Resume all paused polling subscriptions.
+   *
+   * @example
+   * ```typescript
+   * polling.resumeAll();
+   * ```
+   */
+  resumeAll() {
+    for (const id of this.subscriptions.keys()) {
+      this.resume(id);
+    }
+  }
+  /**
+   * Trigger an immediate execution of the polling tick.
+   *
+   * @param id - Subscription identifier
+   * @returns Promise that resolves when the tick completes
+   * @throws Error if the subscription doesn't exist
+   *
+   * @remarks
+   * This does not affect the regular polling schedule. The next scheduled
+   * tick will still occur at the expected time.
+   *
+   * @example
+   * ```typescript
+   * await polling.triggerNow('layer-1');
+   * ```
+   */
+  async triggerNow(id) {
+    const subscription = this.subscriptions.get(id);
+    if (!subscription) {
+      throw new Error(`Polling subscription "${id}" not found`);
+    }
+    await this.executeTick(id);
+  }
+  /**
+   * Get the current state of a polling subscription.
+   *
+   * @param id - Subscription identifier
+   * @returns Current state or null if not found
+   *
+   * @example
+   * ```typescript
+   * const state = polling.getState('layer-1');
+   * if (state) {
+   *   console.log(`Ticks: ${state.tickCount}, Errors: ${state.errorCount}`);
+   * }
+   * ```
+   */
+  getState(id) {
+    const subscription = this.subscriptions.get(id);
+    return subscription ? { ...subscription.state } : null;
+  }
+  /**
+   * Get all active polling subscription IDs.
+   *
+   * @returns Array of subscription IDs
+   *
+   * @example
+   * ```typescript
+   * const ids = polling.getActiveIds();
+   * console.log(`Active pollers: ${ids.join(', ')}`);
+   * ```
+   */
+  getActiveIds() {
+    return Array.from(this.subscriptions.keys());
+  }
+  /**
+   * Check if a polling subscription exists.
+   *
+   * @param id - Subscription identifier
+   * @returns True if the subscription exists
+   *
+   * @example
+   * ```typescript
+   * if (polling.has('layer-1')) {
+   *   polling.pause('layer-1');
+   * }
+   * ```
+   */
+  has(id) {
+    return this.subscriptions.has(id);
+  }
+  /**
+   * Update the interval for an active polling subscription.
+   *
+   * @param id - Subscription identifier
+   * @param interval - New interval in milliseconds (minimum 1000ms)
+   * @throws Error if the subscription doesn't exist
+   *
+   * @remarks
+   * The new interval takes effect after the current tick completes.
+   *
+   * @example
+   * ```typescript
+   * polling.setInterval('layer-1', 10000);
+   * ```
+   */
+  setInterval(id, interval) {
+    const subscription = this.subscriptions.get(id);
+    if (!subscription) {
+      throw new Error(`Polling subscription "${id}" not found`);
+    }
+    if (interval < 1e3) {
+      throw new Error("Interval must be at least 1000ms");
+    }
+    subscription.config.interval = interval;
+    if (!subscription.state.isPaused && !subscription.isExecuting && subscription.timerId !== null) {
+      clearTimeout(subscription.timerId);
+      this.scheduleNextTick(id);
+    }
+  }
+  /**
+   * Clean up all resources and stop all polling.
+   *
+   * @remarks
+   * Should be called when the polling manager is no longer needed.
+   * After calling destroy, the polling manager should not be used.
+   *
+   * @example
+   * ```typescript
+   * polling.destroy();
+   * ```
+   */
+  destroy() {
+    this.stopAll();
+    this.teardownVisibilityListener();
+  }
+  /**
+   * Execute a single tick for a subscription.
+   */
+  async executeTick(id) {
+    const subscription = this.subscriptions.get(id);
+    if (!subscription || subscription.isExecuting) return;
+    subscription.isExecuting = true;
+    try {
+      await subscription.config.onTick();
+      subscription.state.tickCount++;
+      subscription.state.lastTick = Date.now();
+    } catch (error) {
+      subscription.state.errorCount++;
+      const err = error instanceof Error ? error : new Error(String(error));
+      subscription.config.onError?.(err);
+    } finally {
+      subscription.isExecuting = false;
+      if (this.subscriptions.has(id) && subscription.state.isActive && !subscription.state.isPaused) {
+        this.scheduleNextTick(id);
+      }
+    }
+  }
+  /**
+   * Schedule the next tick for a subscription.
+   */
+  scheduleNextTick(id) {
+    const subscription = this.subscriptions.get(id);
+    if (!subscription) return;
+    const nextTime = Date.now() + subscription.config.interval;
+    subscription.state.nextTick = nextTime;
+    subscription.timerId = setTimeout(() => {
+      this.executeTick(id);
+    }, subscription.config.interval);
+  }
+  /**
+   * Setup document visibility listener for automatic pause/resume.
+   */
+  setupVisibilityListener() {
+    if (typeof document === "undefined") return;
+    this.visibilityListener = () => {
+      if (document.hidden) {
+        this.handleVisibilityChange(true);
+      } else {
+        this.handleVisibilityChange(false);
+      }
+    };
+    document.addEventListener("visibilitychange", this.visibilityListener);
+  }
+  /**
+   * Handle document visibility changes.
+   */
+  handleVisibilityChange(hidden) {
+    for (const [id, subscription] of this.subscriptions) {
+      const pauseEnabled = subscription.config.pauseWhenHidden !== false;
+      if (hidden && pauseEnabled && !subscription.state.isPaused) {
+        subscription.pausedByVisibility = true;
+        this.pause(id);
+      } else if (!hidden && pauseEnabled && subscription.pausedByVisibility) {
+        this.resume(id);
+      }
+    }
+  }
+  /**
+   * Remove document visibility listener.
+   */
+  teardownVisibilityListener() {
+    if (this.visibilityListener && typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", this.visibilityListener);
+      this.visibilityListener = null;
+    }
+  }
+};
+
+// src/utils/event-emitter.ts
+var EventEmitter = class {
+  handlers = /* @__PURE__ */ new Map();
+  /**
+   * Register an event handler
+   *
+   * @param event - Event name to listen for
+   * @param handler - Callback function to invoke when event is emitted
+   * @returns Unsubscribe function that removes this specific handler
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = emitter.on('message', (data) => {
+   *   console.log(data.text);
+   * });
+   *
+   * // Later, to unsubscribe:
+   * unsubscribe();
+   * ```
+   */
+  on(event, handler) {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, /* @__PURE__ */ new Set());
+    }
+    this.handlers.get(event).add(handler);
+    return () => this.off(event, handler);
+  }
+  /**
+   * Register a one-time event handler
+   *
+   * @remarks
+   * The handler will be automatically removed after being invoked once.
+   *
+   * @param event - Event name to listen for
+   * @param handler - Callback function to invoke once
+   *
+   * @example
+   * ```typescript
+   * emitter.once('connect', () => {
+   *   console.log('Connected!');
+   * });
+   * ```
+   */
+  once(event, handler) {
+    const onceWrapper = (data) => {
+      this.off(event, onceWrapper);
+      handler(data);
+    };
+    this.on(event, onceWrapper);
+  }
+  /**
+   * Remove an event handler
+   *
+   * @param event - Event name
+   * @param handler - Handler function to remove
+   *
+   * @example
+   * ```typescript
+   * const handler = (data) => console.log(data);
+   * emitter.on('message', handler);
+   * emitter.off('message', handler);
+   * ```
+   */
+  off(event, handler) {
+    const handlers = this.handlers.get(event);
+    if (handlers) {
+      handlers.delete(handler);
+      if (handlers.size === 0) {
+        this.handlers.delete(event);
+      }
+    }
+  }
+  /**
+   * Emit an event to all registered handlers
+   *
+   * @remarks
+   * This method is protected to ensure only the extending class can emit events.
+   * All handlers are invoked synchronously in the order they were registered.
+   *
+   * @param event - Event name to emit
+   * @param data - Event payload data
+   *
+   * @example
+   * ```typescript
+   * class MyEmitter extends EventEmitter<MyEvents> {
+   *   doSomething() {
+   *     this.emit('something-happened', { value: 42 });
+   *   }
+   * }
+   * ```
+   */
+  emit(event, data) {
+    const handlers = this.handlers.get(event);
+    if (handlers) {
+      for (const handler of handlers) {
+        handler(data);
+      }
+    }
+  }
+  /**
+   * Remove all handlers for an event, or all handlers for all events
+   *
+   * @param event - Optional event name. If omitted, removes all handlers for all events.
+   *
+   * @example
+   * ```typescript
+   * // Remove all handlers for 'message' event
+   * emitter.removeAllListeners('message');
+   *
+   * // Remove all handlers for all events
+   * emitter.removeAllListeners();
+   * ```
+   */
+  removeAllListeners(event) {
+    if (event) {
+      this.handlers.delete(event);
+    } else {
+      this.handlers.clear();
+    }
+  }
+  /**
+   * Get the number of handlers registered for an event
+   *
+   * @param event - Event name
+   * @returns Number of registered handlers
+   *
+   * @example
+   * ```typescript
+   * const count = emitter.listenerCount('message');
+   * console.log(`${count} handlers registered`);
+   * ```
+   */
+  listenerCount(event) {
+    const handlers = this.handlers.get(event);
+    return handlers ? handlers.size : 0;
+  }
+  /**
+   * Get all event names that have registered handlers
+   *
+   * @returns Array of event names
+   *
+   * @example
+   * ```typescript
+   * const events = emitter.eventNames();
+   * console.log('Events with handlers:', events);
+   * ```
+   */
+  eventNames() {
+    return Array.from(this.handlers.keys());
+  }
+  /**
+   * Check if an event has any registered handlers
+   *
+   * @param event - Event name
+   * @returns True if the event has at least one handler
+   *
+   * @example
+   * ```typescript
+   * if (emitter.hasListeners('message')) {
+   *   emitter.emit('message', { text: 'Hello' });
+   * }
+   * ```
+   */
+  hasListeners(event) {
+    return this.listenerCount(event) > 0;
+  }
+};
+
+// src/data/streaming/base-connection.ts
+var BaseConnection = class extends EventEmitter {
+  state = "disconnected";
+  config;
+  retryManager;
+  reconnectAttempts = 0;
+  manualDisconnect = false;
+  /**
+   * Create a new base connection.
+   *
+   * @param config - Connection configuration
+   */
+  constructor(config) {
+    super();
+    this.config = {
+      reconnect: true,
+      reconnectConfig: {},
+      ...config
+    };
+    this.retryManager = new RetryManager({
+      maxRetries: 10,
+      initialDelay: 1e3,
+      maxDelay: 3e4,
+      backoffFactor: 2,
+      jitter: true,
+      jitterFactor: 0.25,
+      ...this.config.reconnectConfig
+    });
+  }
+  /**
+   * Get current connection state.
+   *
+   * @returns Current state
+   *
+   * @example
+   * ```typescript
+   * const state = connection.getState();
+   * if (state === 'connected') {
+   *   // Connection is ready
+   * }
+   * ```
+   */
+  getState() {
+    return this.state;
+  }
+  /**
+   * Check if connection is currently connected.
+   *
+   * @returns True if connected
+   *
+   * @example
+   * ```typescript
+   * if (connection.isConnected()) {
+   *   connection.send(data);
+   * }
+   * ```
+   */
+  isConnected() {
+    return this.state === "connected";
+  }
+  /**
+   * Get the number of reconnection attempts.
+   *
+   * @returns Number of reconnect attempts
+   */
+  getReconnectAttempts() {
+    return this.reconnectAttempts;
+  }
+  /**
+   * Update connection state and emit state change event.
+   *
+   * @param newState - New connection state
+   *
+   * @remarks
+   * Automatically emits 'stateChange' event when state changes.
+   * Subclasses should call this method instead of setting state directly.
+   *
+   * @example
+   * ```typescript
+   * protected async connect() {
+   *   this.setState('connecting');
+   *   await this.establishConnection();
+   *   this.setState('connected');
+   * }
+   * ```
+   */
+  setState(newState) {
+    if (this.state === newState) return;
+    const oldState = this.state;
+    this.state = newState;
+    this.emit("stateChange", { from: oldState, to: newState });
+  }
+  /**
+   * Handle disconnection and optionally attempt reconnection.
+   *
+   * @param reason - Reason for disconnection
+   *
+   * @remarks
+   * This method should be called by subclasses when the connection is lost.
+   * It will:
+   * 1. Emit 'disconnect' event
+   * 2. Attempt reconnection if enabled and not manually disconnected
+   * 3. Emit 'reconnecting', 'reconnected', or 'failed' events as appropriate
+   *
+   * @example
+   * ```typescript
+   * ws.onclose = () => {
+   *   this.handleDisconnect('Connection closed');
+   * };
+   * ```
+   */
+  async handleDisconnect(reason) {
+    const wasConnected = this.state === "connected";
+    this.setState("disconnected");
+    this.emit("disconnect", { reason });
+    if (!this.config.reconnect || this.manualDisconnect || !wasConnected) {
+      return;
+    }
+    await this.attemptReconnection();
+  }
+  /**
+   * Attempt to reconnect with exponential backoff.
+   */
+  async attemptReconnection() {
+    this.setState("reconnecting");
+    this.reconnectAttempts = 0;
+    try {
+      await this.retryManager.execute(
+        async () => {
+          this.reconnectAttempts++;
+          await this.connect();
+        },
+        {
+          onRetry: (attempt, delay) => {
+            this.emit("reconnecting", { attempt, delay });
+          },
+          onSuccess: (attempts) => {
+            this.reconnectAttempts = 0;
+            this.emit("reconnected", { attempts });
+          }
+        }
+      );
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.setState("failed");
+      this.emit("failed", {
+        attempts: this.reconnectAttempts,
+        lastError: error
+      });
+    }
+  }
+  /**
+   * Mark disconnection as manual to prevent reconnection.
+   *
+   * @remarks
+   * Should be called by subclasses in their disconnect() implementation
+   * before closing the connection.
+   *
+   * @example
+   * ```typescript
+   * disconnect(): void {
+   *   this.setManualDisconnect();
+   *   this.ws.close();
+   * }
+   * ```
+   */
+  setManualDisconnect() {
+    this.manualDisconnect = true;
+  }
+  /**
+   * Reset manual disconnect flag.
+   *
+   * @remarks
+   * Should be called when establishing a new connection to allow
+   * automatic reconnection for subsequent disconnections.
+   */
+  resetManualDisconnect() {
+    this.manualDisconnect = false;
+  }
+};
+
+// src/data/streaming/sse-connection.ts
+var SSEConnection = class extends BaseConnection {
+  eventSource = null;
+  lastEventId = null;
+  sseConfig;
+  /**
+   * Create a new SSE connection.
+   *
+   * @param config - SSE configuration
+   *
+   * @example
+   * ```typescript
+   * const connection = new SSEConnection({
+   *   url: 'https://api.example.com/stream',
+   *   eventTypes: ['message', 'update'],
+   *   withCredentials: true,
+   * });
+   * ```
+   */
+  constructor(config) {
+    super(config);
+    this.sseConfig = {
+      ...this.config,
+      eventTypes: config.eventTypes ?? ["message"],
+      withCredentials: config.withCredentials ?? false
+    };
+  }
+  /**
+   * Establish SSE connection.
+   *
+   * @remarks
+   * Creates an EventSource and sets up event listeners for:
+   * - Connection open
+   * - Message events (for each configured event type)
+   * - Error events
+   *
+   * The EventSource API handles reconnection automatically when the
+   * connection is lost, unless explicitly closed.
+   *
+   * @throws Error if EventSource is not supported or connection fails
+   *
+   * @example
+   * ```typescript
+   * await connection.connect();
+   * console.log('Connected to SSE stream');
+   * ```
+   */
+  async connect() {
+    if (this.eventSource !== null) {
+      throw new Error("Connection already exists");
+    }
+    this.setState("connecting");
+    try {
+      this.eventSource = new EventSource(this.sseConfig.url, {
+        withCredentials: this.sseConfig.withCredentials
+      });
+      await new Promise((resolve, reject) => {
+        if (!this.eventSource) {
+          reject(new Error("EventSource not created"));
+          return;
+        }
+        const onOpen = () => {
+          cleanup();
+          this.setState("connected");
+          this.resetManualDisconnect();
+          this.emit("connect", void 0);
+          resolve();
+        };
+        const onError = () => {
+          cleanup();
+          const error = new Error("Failed to connect to SSE stream");
+          this.emit("error", { error });
+          reject(error);
+        };
+        const cleanup = () => {
+          this.eventSource?.removeEventListener("open", onOpen);
+          this.eventSource?.removeEventListener("error", onError);
+        };
+        this.eventSource.addEventListener("open", onOpen);
+        this.eventSource.addEventListener("error", onError);
+      });
+      this.setupEventListeners();
+    } catch (error) {
+      this.closeEventSource();
+      throw error;
+    }
+  }
+  /**
+   * Close SSE connection.
+   *
+   * @remarks
+   * Closes the EventSource and cleans up all event listeners.
+   * Sets the manual disconnect flag to prevent automatic reconnection.
+   *
+   * @example
+   * ```typescript
+   * connection.disconnect();
+   * console.log('Disconnected from SSE stream');
+   * ```
+   */
+  disconnect() {
+    this.setManualDisconnect();
+    this.closeEventSource();
+    this.handleDisconnect("Manual disconnect");
+  }
+  /**
+   * Get the last event ID received from the server.
+   *
+   * @returns Last event ID or null if none received
+   *
+   * @remarks
+   * The event ID is used by the EventSource API to resume the stream
+   * from the last received event after a reconnection. The browser
+   * automatically sends this ID in the `Last-Event-ID` header.
+   *
+   * @example
+   * ```typescript
+   * const lastId = connection.getLastEventId();
+   * if (lastId) {
+   *   console.log(`Last event: ${lastId}`);
+   * }
+   * ```
+   */
+  getLastEventId() {
+    return this.lastEventId;
+  }
+  /**
+   * Setup event listeners for configured event types.
+   */
+  setupEventListeners() {
+    if (!this.eventSource) return;
+    for (const eventType of this.sseConfig.eventTypes) {
+      this.eventSource.addEventListener(eventType, (event) => {
+        this.handleMessage(event);
+      });
+    }
+    this.eventSource.addEventListener("error", () => {
+      this.handleError();
+    });
+  }
+  /**
+   * Handle incoming message event.
+   */
+  handleMessage(event) {
+    if (event.lastEventId) {
+      this.lastEventId = event.lastEventId;
+    }
+    try {
+      const data = JSON.parse(event.data);
+      this.emit("message", { data });
+    } catch (error) {
+      const parseError = new Error(
+        `Failed to parse SSE message as JSON: ${event.data}`
+      );
+      this.emit("error", { error: parseError });
+    }
+  }
+  /**
+   * Handle error event from EventSource.
+   */
+  handleError() {
+    if (this.state === "connected") {
+      const error = new Error("SSE connection error");
+      this.emit("error", { error });
+      if (this.eventSource?.readyState === EventSource.CLOSED) {
+        this.closeEventSource();
+        this.handleDisconnect("Connection closed by server");
+      }
+    }
+  }
+  /**
+   * Close EventSource and clean up.
+   */
+  closeEventSource() {
+    if (this.eventSource) {
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+  }
+};
+
+// src/data/streaming/websocket-connection.ts
+var WebSocketConnection = class extends BaseConnection {
+  ws = null;
+  wsConfig;
+  /**
+   * Create a new WebSocket connection.
+   *
+   * @param config - WebSocket configuration
+   *
+   * @example
+   * ```typescript
+   * const connection = new WebSocketConnection({
+   *   url: 'wss://api.example.com/stream',
+   *   protocols: ['json', 'v1'],
+   * });
+   * ```
+   */
+  constructor(config) {
+    super(config);
+    this.wsConfig = {
+      ...this.config,
+      protocols: config.protocols
+    };
+  }
+  /**
+   * Establish WebSocket connection.
+   *
+   * @remarks
+   * Creates a WebSocket and sets up event listeners for:
+   * - Connection open
+   * - Message reception
+   * - Connection close
+   * - Errors
+   *
+   * Unlike EventSource, WebSocket does not have built-in reconnection,
+   * so reconnection is handled manually via the BaseConnection.
+   *
+   * @throws Error if WebSocket is not supported or connection fails
+   *
+   * @example
+   * ```typescript
+   * await connection.connect();
+   * console.log('Connected to WebSocket');
+   * ```
+   */
+  async connect() {
+    if (this.ws !== null) {
+      throw new Error("Connection already exists");
+    }
+    this.setState("connecting");
+    try {
+      this.ws = this.wsConfig.protocols ? new WebSocket(this.wsConfig.url, this.wsConfig.protocols) : new WebSocket(this.wsConfig.url);
+      await new Promise((resolve, reject) => {
+        if (!this.ws) {
+          reject(new Error("WebSocket not created"));
+          return;
+        }
+        const onOpen = () => {
+          cleanup();
+          this.setState("connected");
+          this.resetManualDisconnect();
+          this.emit("connect", void 0);
+          resolve();
+        };
+        const onError = () => {
+          cleanup();
+          const error = new Error("Failed to connect to WebSocket");
+          this.emit("error", { error });
+          reject(error);
+        };
+        const cleanup = () => {
+          if (this.ws) {
+            this.ws.removeEventListener("open", onOpen);
+            this.ws.removeEventListener("error", onError);
+          }
+        };
+        this.ws.addEventListener("open", onOpen);
+        this.ws.addEventListener("error", onError);
+      });
+      this.setupEventListeners();
+    } catch (error) {
+      this.closeWebSocket();
+      throw error;
+    }
+  }
+  /**
+   * Close WebSocket connection.
+   *
+   * @remarks
+   * Closes the WebSocket with a normal closure code (1000).
+   * Sets the manual disconnect flag to prevent automatic reconnection.
+   *
+   * @example
+   * ```typescript
+   * connection.disconnect();
+   * console.log('Disconnected from WebSocket');
+   * ```
+   */
+  disconnect() {
+    this.setManualDisconnect();
+    this.closeWebSocket();
+    this.handleDisconnect("Manual disconnect");
+  }
+  /**
+   * Send data through WebSocket.
+   *
+   * @param data - Data to send (will be JSON stringified)
+   * @throws Error if not connected
+   *
+   * @remarks
+   * The data is automatically converted to JSON before sending.
+   * Throws an error if called when the connection is not established.
+   *
+   * @example
+   * ```typescript
+   * connection.send({ type: 'ping' });
+   * connection.send({ type: 'subscribe', channel: 'updates' });
+   * ```
+   */
+  send(data) {
+    if (!this.isConnected() || !this.ws) {
+      throw new Error("Cannot send: not connected");
+    }
+    const message = JSON.stringify(data);
+    this.ws.send(message);
+  }
+  /**
+   * Setup WebSocket event listeners.
+   */
+  setupEventListeners() {
+    if (!this.ws) return;
+    this.ws.addEventListener("message", (event) => {
+      this.handleMessage(event);
+    });
+    this.ws.addEventListener("close", (event) => {
+      this.handleClose(event);
+    });
+    this.ws.addEventListener("error", () => {
+      this.handleError();
+    });
+  }
+  /**
+   * Handle incoming message event.
+   */
+  handleMessage(event) {
+    try {
+      const data = JSON.parse(event.data);
+      this.emit("message", { data });
+    } catch {
+      this.emit("message", { data: event.data });
+    }
+  }
+  /**
+   * Handle close event from WebSocket.
+   */
+  handleClose(event) {
+    this.closeWebSocket();
+    const reason = event.reason || `WebSocket closed (code: ${event.code})`;
+    this.handleDisconnect(reason);
+  }
+  /**
+   * Handle error event from WebSocket.
+   */
+  handleError() {
+    if (this.state === "connecting" || this.state === "connected") {
+      const error = new Error("WebSocket connection error");
+      this.emit("error", { error });
+    }
+  }
+  /**
+   * Close WebSocket and clean up.
+   */
+  closeWebSocket() {
+    if (this.ws) {
+      if (this.ws.readyState === WebSocket.OPEN) {
+        this.ws.close(1e3, "Normal closure");
+      }
+      this.ws = null;
+    }
+  }
+};
+
+// src/data/streaming/stream-manager.ts
+var StreamManager = class {
+  subscriptions = /* @__PURE__ */ new Map();
+  /**
+   * Connect to a streaming source.
+   *
+   * @param id - Unique identifier for this connection
+   * @param config - Stream configuration
+   * @throws {Error} If a connection with the given id already exists
+   *
+   * @example
+   * ```typescript
+   * await manager.connect('updates', {
+   *   type: 'sse',
+   *   url: 'https://api.example.com/stream',
+   *   onData: (data) => console.log(data)
+   * });
+   * ```
+   */
+  async connect(id, config) {
+    if (this.subscriptions.has(id)) {
+      throw new Error(`Stream with id "${id}" already exists`);
+    }
+    const connection = this.createConnection(config);
+    const state = {
+      connectionState: "disconnected",
+      messageCount: 0,
+      lastMessage: null,
+      reconnectAttempts: 0
+    };
+    this.subscriptions.set(id, { config, connection, state });
+    this.setupEventHandlers(connection, config, state);
+    await connection.connect();
+  }
+  /**
+   * Disconnect a specific stream.
+   *
+   * @param id - Stream identifier
+   *
+   * @example
+   * ```typescript
+   * manager.disconnect('updates');
+   * ```
+   */
+  disconnect(id) {
+    const subscription = this.subscriptions.get(id);
+    if (!subscription) {
+      return;
+    }
+    subscription.connection.disconnect();
+    this.subscriptions.delete(id);
+  }
+  /**
+   * Disconnect all active streams.
+   *
+   * @example
+   * ```typescript
+   * manager.disconnectAll();
+   * ```
+   */
+  disconnectAll() {
+    for (const id of this.subscriptions.keys()) {
+      this.disconnect(id);
+    }
+  }
+  /**
+   * Get the current state of a stream.
+   *
+   * @param id - Stream identifier
+   * @returns Stream state or null if not found
+   *
+   * @example
+   * ```typescript
+   * const state = manager.getState('updates');
+   * if (state) {
+   *   console.log(`State: ${state.connectionState}`);
+   *   console.log(`Messages: ${state.messageCount}`);
+   * }
+   * ```
+   */
+  getState(id) {
+    const subscription = this.subscriptions.get(id);
+    return subscription ? { ...subscription.state } : null;
+  }
+  /**
+   * Check if a stream is currently connected.
+   *
+   * @param id - Stream identifier
+   * @returns True if connected, false otherwise
+   *
+   * @example
+   * ```typescript
+   * if (manager.isConnected('updates')) {
+   *   console.log('Stream is active');
+   * }
+   * ```
+   */
+  isConnected(id) {
+    const subscription = this.subscriptions.get(id);
+    return subscription ? subscription.connection.isConnected() : false;
+  }
+  /**
+   * Get all active stream IDs.
+   *
+   * @returns Array of active stream identifiers
+   *
+   * @example
+   * ```typescript
+   * const activeStreams = manager.getActiveIds();
+   * console.log(`Active streams: ${activeStreams.join(', ')}`);
+   * ```
+   */
+  getActiveIds() {
+    return Array.from(this.subscriptions.keys());
+  }
+  /**
+   * Send data to a WebSocket connection.
+   *
+   * @param id - Stream identifier
+   * @param data - Data to send (will be JSON stringified)
+   * @throws {Error} If stream is not a WebSocket connection or not connected
+   *
+   * @example
+   * ```typescript
+   * manager.send('ws-updates', {
+   *   type: 'subscribe',
+   *   channels: ['news', 'sports']
+   * });
+   * ```
+   */
+  send(id, data) {
+    const subscription = this.subscriptions.get(id);
+    if (!subscription) {
+      throw new Error(`Stream "${id}" not found`);
+    }
+    if (!(subscription.connection instanceof WebSocketConnection)) {
+      throw new Error(`Stream "${id}" is not a WebSocket connection`);
+    }
+    subscription.connection.send(data);
+  }
+  /**
+   * Clean up all resources.
+   *
+   * @example
+   * ```typescript
+   * manager.destroy();
+   * ```
+   */
+  destroy() {
+    this.disconnectAll();
+  }
+  /**
+   * Create a connection instance based on config type.
+   */
+  createConnection(config) {
+    const reconnectConfig = config.reconnect?.enabled !== false ? {
+      reconnect: true,
+      retryConfig: {
+        maxRetries: config.reconnect?.maxRetries ?? 10,
+        initialDelay: config.reconnect?.initialDelay ?? 1e3,
+        maxDelay: config.reconnect?.maxDelay ?? 3e4
+      }
+    } : { reconnect: false };
+    if (config.type === "sse") {
+      const sseConfig = {
+        url: config.url,
+        ...reconnectConfig,
+        eventTypes: config.eventTypes
+      };
+      return new SSEConnection(sseConfig);
+    } else {
+      const wsConfig = {
+        url: config.url,
+        ...reconnectConfig,
+        protocols: config.protocols
+      };
+      return new WebSocketConnection(wsConfig);
+    }
+  }
+  /**
+   * Setup event handlers for a connection.
+   */
+  setupEventHandlers(connection, config, state) {
+    connection.on("stateChange", ({ to }) => {
+      state.connectionState = to;
+      config.onStateChange?.(to);
+    });
+    connection.on("message", ({ data }) => {
+      state.messageCount++;
+      state.lastMessage = Date.now();
+      if (this.isFeatureCollection(data)) {
+        config.onData(data);
+      } else {
+        const error = new Error(
+          "Received data is not a valid GeoJSON FeatureCollection"
+        );
+        config.onError?.(error);
+      }
+    });
+    connection.on("error", ({ error }) => {
+      config.onError?.(error);
+    });
+    connection.on("reconnecting", () => {
+      state.reconnectAttempts++;
+    });
+    connection.on("reconnected", () => {
+      state.reconnectAttempts = 0;
+    });
+    connection.on("failed", ({ lastError }) => {
+      config.onError?.(lastError);
+    });
+  }
+  /**
+   * Type guard to check if data is a FeatureCollection.
+   */
+  isFeatureCollection(data) {
+    return typeof data === "object" && data !== null && "type" in data && data.type === "FeatureCollection" && "features" in data && Array.isArray(data.features);
+  }
+};
+
+// src/data/merge/data-merger.ts
+var DataMerger = class {
+  /**
+   * Merge two FeatureCollections using the specified strategy.
+   *
+   * @param existing - Existing feature collection
+   * @param incoming - Incoming feature collection to merge
+   * @param options - Merge options including strategy
+   * @returns Merge result with statistics
+   * @throws {Error} If merge strategy requires missing options
+   *
+   * @example
+   * ```typescript
+   * const merger = new DataMerger();
+   *
+   * const result = merger.merge(existingData, newData, {
+   *   strategy: 'merge',
+   *   updateKey: 'id'
+   * });
+   *
+   * console.log(`Added: ${result.added}, Updated: ${result.updated}`);
+   * console.log(`Total features: ${result.total}`);
+   * ```
+   */
+  merge(existing, incoming, options) {
+    switch (options.strategy) {
+      case "replace":
+        return this.mergeReplace(existing, incoming);
+      case "merge":
+        return this.mergeMerge(existing, incoming, options);
+      case "append-window":
+        return this.mergeAppendWindow(existing, incoming, options);
+      default:
+        throw new Error(
+          `Unknown merge strategy: ${options.strategy}`
+        );
+    }
+  }
+  /**
+   * Replace strategy: Complete replacement of existing data.
+   */
+  mergeReplace(existing, incoming) {
+    return {
+      data: incoming,
+      added: incoming.features.length,
+      updated: 0,
+      removed: existing.features.length,
+      total: incoming.features.length
+    };
+  }
+  /**
+   * Merge strategy: Update by key, keep unmatched features.
+   */
+  mergeMerge(existing, incoming, options) {
+    if (!options.updateKey) {
+      throw new Error("updateKey is required for merge strategy");
+    }
+    const updateKey = options.updateKey;
+    let added = 0;
+    let updated = 0;
+    const existingMap = /* @__PURE__ */ new Map();
+    for (const feature of existing.features) {
+      const key = feature.properties?.[updateKey];
+      if (key !== void 0 && key !== null) {
+        existingMap.set(key, feature);
+      }
+    }
+    for (const feature of incoming.features) {
+      const key = feature.properties?.[updateKey];
+      if (key !== void 0 && key !== null) {
+        if (existingMap.has(key)) {
+          updated++;
+        } else {
+          added++;
+        }
+        existingMap.set(key, feature);
+      }
+    }
+    const features = Array.from(existingMap.values());
+    return {
+      data: {
+        type: "FeatureCollection",
+        features
+      },
+      added,
+      updated,
+      removed: 0,
+      total: features.length
+    };
+  }
+  /**
+   * Append-window strategy: Add with time/size limits.
+   */
+  mergeAppendWindow(existing, incoming, options) {
+    const initialCount = existing.features.length;
+    let features = [...existing.features, ...incoming.features];
+    if (options.windowDuration && options.timestampField) {
+      const cutoffTime = Date.now() - options.windowDuration;
+      features = features.filter((feature) => {
+        const timestamp = feature.properties?.[options.timestampField];
+        if (typeof timestamp === "number") {
+          return timestamp >= cutoffTime;
+        }
+        return true;
+      });
+      features.sort((a, b) => {
+        const timeA = a.properties?.[options.timestampField] ?? 0;
+        const timeB = b.properties?.[options.timestampField] ?? 0;
+        return timeB - timeA;
+      });
+      if (options.windowSize && features.length > options.windowSize) {
+        features = features.slice(0, options.windowSize);
+      }
+      const removed2 = initialCount + incoming.features.length - features.length;
+      return {
+        data: {
+          type: "FeatureCollection",
+          features
+        },
+        added: incoming.features.length,
+        updated: 0,
+        removed: removed2,
+        total: features.length
+      };
+    }
+    if (options.windowSize) {
+      if (options.timestampField) {
+        features.sort((a, b) => {
+          const timeA = a.properties?.[options.timestampField] ?? 0;
+          const timeB = b.properties?.[options.timestampField] ?? 0;
+          return timeB - timeA;
+        });
+      }
+      if (features.length > options.windowSize) {
+        features = features.slice(0, options.windowSize);
+      }
+    }
+    const removed = initialCount + incoming.features.length - features.length;
+    return {
+      data: {
+        type: "FeatureCollection",
+        features
+      },
+      added: incoming.features.length,
+      updated: 0,
+      removed,
+      total: features.length
+    };
+  }
+};
+
+// src/ui/loading-manager.ts
+var LoadingManager = class _LoadingManager extends EventEmitter {
+  config;
+  subscriptions = /* @__PURE__ */ new Map();
+  static DEFAULT_CONFIG = {
+    showUI: false,
+    messages: {
+      loading: "Loading...",
+      error: "Failed to load data",
+      retry: "Retrying..."
+    },
+    spinnerStyle: "circle",
+    minDisplayTime: 300
+  };
+  /**
+   * Create a new LoadingManager.
+   *
+   * @param config - Loading manager configuration
+   *
+   * @example
+   * ```typescript
+   * const manager = new LoadingManager({
+   *   showUI: true,
+   *   messages: {
+   *     loading: 'Fetching data...',
+   *     error: 'Could not load data'
+   *   },
+   *   spinnerStyle: 'dots',
+   *   minDisplayTime: 500
+   * });
+   * ```
+   */
+  constructor(config) {
+    super();
+    this.config = {
+      ..._LoadingManager.DEFAULT_CONFIG,
+      ...config,
+      messages: {
+        ..._LoadingManager.DEFAULT_CONFIG.messages,
+        ...config?.messages
+      }
+    };
+  }
+  /**
+   * Show loading state for a layer.
+   *
+   * @param layerId - Layer identifier
+   * @param container - Container element for UI overlay
+   * @param message - Custom loading message
+   *
+   * @example
+   * ```typescript
+   * const container = document.getElementById('map');
+   * manager.showLoading('earthquakes', container, 'Loading earthquake data...');
+   * ```
+   */
+  showLoading(layerId, container, message) {
+    const existingSub = this.subscriptions.get(layerId);
+    if (existingSub?.state.isLoading) {
+      return;
+    }
+    const state = {
+      isLoading: true,
+      startTime: Date.now(),
+      message: message || this.config.messages.loading
+    };
+    let overlay = null;
+    if (this.config.showUI) {
+      overlay = this.createLoadingOverlay(
+        state.message || this.config.messages.loading || "Loading..."
+      );
+      container.style.position = "relative";
+      container.appendChild(overlay);
+    }
+    this.subscriptions.set(layerId, {
+      state,
+      container,
+      overlay,
+      minDisplayTimer: null
+    });
+    this.emit("loading:start", { layerId, message: state.message });
+  }
+  /**
+   * Hide loading state for a layer.
+   *
+   * @param layerId - Layer identifier
+   * @param result - Optional result information
+   *
+   * @example
+   * ```typescript
+   * manager.hideLoading('earthquakes', { fromCache: true });
+   * ```
+   */
+  hideLoading(layerId, result) {
+    const subscription = this.subscriptions.get(layerId);
+    if (!subscription?.state.isLoading) {
+      return;
+    }
+    const duration = Date.now() - (subscription.state.startTime || Date.now());
+    const timeRemaining = Math.max(0, this.config.minDisplayTime - duration);
+    const cleanup = () => {
+      if (subscription.overlay) {
+        subscription.overlay.remove();
+      }
+      subscription.state.isLoading = false;
+      subscription.state.startTime = null;
+      subscription.state.error = void 0;
+      subscription.state.retryAttempt = void 0;
+      this.emit("loading:complete", {
+        layerId,
+        duration,
+        fromCache: result?.fromCache ?? false
+      });
+    };
+    if (timeRemaining > 0 && subscription.overlay) {
+      subscription.minDisplayTimer = window.setTimeout(cleanup, timeRemaining);
+    } else {
+      cleanup();
+    }
+  }
+  /**
+   * Show error state for a layer.
+   *
+   * @param layerId - Layer identifier
+   * @param container - Container element for UI overlay
+   * @param error - Error that occurred
+   * @param onRetry - Optional retry callback
+   *
+   * @example
+   * ```typescript
+   * manager.showError('earthquakes', container, error, () => {
+   *   // Retry loading
+   *   fetchData();
+   * });
+   * ```
+   */
+  showError(layerId, container, error, onRetry) {
+    const subscription = this.subscriptions.get(layerId);
+    const state = subscription?.state || {
+      isLoading: false,
+      startTime: null
+    };
+    state.error = error;
+    state.isLoading = false;
+    if (subscription?.overlay) {
+      subscription.overlay.remove();
+    }
+    let overlay = null;
+    if (this.config.showUI) {
+      overlay = this.createErrorOverlay(
+        error.message || this.config.messages.error || "An error occurred",
+        onRetry
+      );
+      container.style.position = "relative";
+      container.appendChild(overlay);
+    }
+    this.subscriptions.set(layerId, {
+      state,
+      container,
+      overlay,
+      minDisplayTimer: null
+    });
+    this.emit("loading:error", {
+      layerId,
+      error,
+      retrying: !!onRetry
+    });
+  }
+  /**
+   * Show retrying state for a layer.
+   *
+   * @param layerId - Layer identifier
+   * @param attempt - Current retry attempt number
+   * @param delay - Delay before retry in milliseconds
+   *
+   * @example
+   * ```typescript
+   * manager.showRetrying('earthquakes', 2, 2000);
+   * ```
+   */
+  showRetrying(layerId, attempt, delay) {
+    const subscription = this.subscriptions.get(layerId);
+    if (subscription) {
+      subscription.state.retryAttempt = attempt;
+      if (subscription.overlay && this.config.showUI) {
+        const message = `${this.config.messages.retry} (attempt ${attempt})`;
+        const newOverlay = this.createLoadingOverlay(message);
+        subscription.overlay.replaceWith(newOverlay);
+        subscription.overlay = newOverlay;
+      }
+    }
+    this.emit("loading:retry", { layerId, attempt, delay });
+  }
+  /**
+   * Get loading state for a layer.
+   *
+   * @param layerId - Layer identifier
+   * @returns Loading state or null if not found
+   *
+   * @example
+   * ```typescript
+   * const state = manager.getState('earthquakes');
+   * if (state?.isLoading) {
+   *   console.log('Still loading...');
+   * }
+   * ```
+   */
+  getState(layerId) {
+    const subscription = this.subscriptions.get(layerId);
+    return subscription ? { ...subscription.state } : null;
+  }
+  /**
+   * Check if a layer is currently loading.
+   *
+   * @param layerId - Layer identifier
+   * @returns True if loading, false otherwise
+   *
+   * @example
+   * ```typescript
+   * if (manager.isLoading('earthquakes')) {
+   *   console.log('Loading in progress');
+   * }
+   * ```
+   */
+  isLoading(layerId) {
+    return this.subscriptions.get(layerId)?.state.isLoading ?? false;
+  }
+  /**
+   * Clear all loading states and UI.
+   *
+   * @example
+   * ```typescript
+   * manager.clearAll();
+   * ```
+   */
+  clearAll() {
+    for (const [layerId, subscription] of this.subscriptions.entries()) {
+      if (subscription.minDisplayTimer) {
+        clearTimeout(subscription.minDisplayTimer);
+      }
+      if (subscription.overlay) {
+        subscription.overlay.remove();
+      }
+      this.subscriptions.delete(layerId);
+    }
+  }
+  /**
+   * Clean up all resources.
+   *
+   * @example
+   * ```typescript
+   * manager.destroy();
+   * ```
+   */
+  destroy() {
+    this.clearAll();
+    this.removeAllListeners();
+  }
+  /**
+   * Create loading overlay element.
+   */
+  createLoadingOverlay(message) {
+    const overlay = document.createElement("div");
+    overlay.className = "mly-loading-overlay";
+    const content = document.createElement("div");
+    content.className = "mly-loading-content";
+    const spinner = document.createElement("div");
+    spinner.className = `mly-spinner mly-spinner--${this.config.spinnerStyle}`;
+    const text = document.createElement("div");
+    text.className = "mly-loading-text";
+    text.textContent = message;
+    content.appendChild(spinner);
+    content.appendChild(text);
+    overlay.appendChild(content);
+    return overlay;
+  }
+  /**
+   * Create error overlay element.
+   */
+  createErrorOverlay(message, onRetry) {
+    const overlay = document.createElement("div");
+    overlay.className = "mly-loading-overlay mly-loading-overlay--error";
+    const content = document.createElement("div");
+    content.className = "mly-error-content";
+    const icon = document.createElement("div");
+    icon.className = "mly-error-icon";
+    icon.textContent = "\u26A0";
+    const text = document.createElement("div");
+    text.className = "mly-error-text";
+    text.textContent = message;
+    content.appendChild(icon);
+    content.appendChild(text);
+    if (onRetry) {
+      const button = document.createElement("button");
+      button.className = "mly-retry-button";
+      button.textContent = "Retry";
+      button.onclick = () => {
+        overlay.remove();
+        onRetry();
+      };
+      content.appendChild(button);
+    }
+    overlay.appendChild(content);
+    return overlay;
+  }
+};
+
+// src/renderer/layer-manager.ts
+var LayerManager = class {
+  map;
+  callbacks;
+  dataFetcher;
+  pollingManager;
+  streamManager;
+  dataMerger;
+  loadingManager;
+  sourceData;
+  layerToSource;
+  // Legacy support (deprecated)
+  refreshIntervals;
+  abortControllers;
+  constructor(map, callbacks) {
+    this.map = map;
+    this.callbacks = callbacks || {};
+    this.dataFetcher = new DataFetcher();
+    this.pollingManager = new PollingManager();
+    this.streamManager = new StreamManager();
+    this.dataMerger = new DataMerger();
+    this.loadingManager = new LoadingManager({ showUI: false });
+    this.sourceData = /* @__PURE__ */ new Map();
+    this.layerToSource = /* @__PURE__ */ new Map();
+    this.refreshIntervals = /* @__PURE__ */ new Map();
+    this.abortControllers = /* @__PURE__ */ new Map();
+  }
+  async addLayer(layer) {
+    const sourceId = `${layer.id}-source`;
+    this.layerToSource.set(layer.id, sourceId);
+    await this.addSource(sourceId, layer);
+    const layerSpec = {
+      id: layer.id,
+      type: layer.type,
+      source: sourceId
+    };
+    if ("paint" in layer && layer.paint) layerSpec.paint = layer.paint;
+    if ("layout" in layer && layer.layout) layerSpec.layout = layer.layout;
+    if ("source-layer" in layer && layer["source-layer"])
+      layerSpec["source-layer"] = layer["source-layer"];
+    if (layer.minzoom !== void 0) layerSpec.minzoom = layer.minzoom;
+    if (layer.maxzoom !== void 0) layerSpec.maxzoom = layer.maxzoom;
+    if (layer.filter) layerSpec.filter = layer.filter;
+    if (layer.visible === false) {
+      layerSpec.layout = layerSpec.layout || {};
+      layerSpec.layout.visibility = "none";
+    }
+    this.map.addLayer(layerSpec, layer.before);
+    if (typeof layer.source === "object" && layer.source !== null) {
+      const sourceObj = layer.source;
+      if (sourceObj.type === "geojson") {
+        if (sourceObj.refresh || sourceObj.refreshInterval) {
+          await this.setupDataUpdates(layer.id, sourceId, sourceObj);
+        }
+      }
+    }
+  }
+  async addSource(sourceId, layer) {
+    if (typeof layer.source === "string") {
+      if (!this.map.getSource(layer.source)) {
+        throw new Error(`Source reference '${layer.source}' not found`);
+      }
+      return;
+    }
+    const source = layer.source;
+    if (source.type === "geojson") {
+      const geojsonSource = source;
+      if (geojsonSource.url) {
+        await this.addGeoJSONSourceFromURL(sourceId, layer.id, geojsonSource);
+      } else if (geojsonSource.data) {
+        this.map.addSource(sourceId, {
+          type: "geojson",
+          data: geojsonSource.data,
+          cluster: geojsonSource.cluster,
+          clusterRadius: geojsonSource.clusterRadius,
+          clusterMaxZoom: geojsonSource.clusterMaxZoom,
+          clusterMinPoints: geojsonSource.clusterMinPoints,
+          clusterProperties: geojsonSource.clusterProperties
+        });
+      } else if (geojsonSource.stream) {
+        this.map.addSource(sourceId, {
+          type: "geojson",
+          data: { type: "FeatureCollection", features: [] }
+        });
+      }
+    } else if (source.type === "vector") {
+      const vectorSource = source;
+      const vectorSpec = { type: "vector" };
+      if (vectorSource.url) vectorSpec.url = vectorSource.url;
+      if (vectorSource.tiles) vectorSpec.tiles = vectorSource.tiles;
+      if (vectorSource.minzoom !== void 0)
+        vectorSpec.minzoom = vectorSource.minzoom;
+      if (vectorSource.maxzoom !== void 0)
+        vectorSpec.maxzoom = vectorSource.maxzoom;
+      if (vectorSource.bounds) vectorSpec.bounds = vectorSource.bounds;
+      if (vectorSource.attribution)
+        vectorSpec.attribution = vectorSource.attribution;
+      this.map.addSource(sourceId, vectorSpec);
+    } else if (source.type === "raster") {
+      const rasterSource = source;
+      const rasterSpec = { type: "raster" };
+      if (rasterSource.url) rasterSpec.url = rasterSource.url;
+      if (rasterSource.tiles) rasterSpec.tiles = rasterSource.tiles;
+      if (rasterSource.tileSize !== void 0)
+        rasterSpec.tileSize = rasterSource.tileSize;
+      if (rasterSource.minzoom !== void 0)
+        rasterSpec.minzoom = rasterSource.minzoom;
+      if (rasterSource.maxzoom !== void 0)
+        rasterSpec.maxzoom = rasterSource.maxzoom;
+      if (rasterSource.bounds) rasterSpec.bounds = rasterSource.bounds;
+      if (rasterSource.attribution)
+        rasterSpec.attribution = rasterSource.attribution;
+      this.map.addSource(sourceId, rasterSpec);
+    } else if (source.type === "image") {
+      const imageSource = source;
+      this.map.addSource(sourceId, {
+        type: "image",
+        url: imageSource.url,
+        coordinates: imageSource.coordinates
+      });
+    } else if (source.type === "video") {
+      const videoSource = source;
+      this.map.addSource(sourceId, {
+        type: "video",
+        urls: videoSource.urls,
+        coordinates: videoSource.coordinates
+      });
+    }
+  }
+  async addGeoJSONSourceFromURL(sourceId, layerId, config) {
+    let initialData = {
+      type: "FeatureCollection",
+      features: []
+    };
+    if (config.prefetchedData) {
+      initialData = config.prefetchedData;
+    } else if (config.data) {
+      initialData = config.data;
+    }
+    this.map.addSource(sourceId, {
+      type: "geojson",
+      data: initialData,
+      cluster: config.cluster,
+      clusterRadius: config.clusterRadius,
+      clusterMaxZoom: config.clusterMaxZoom,
+      clusterMinPoints: config.clusterMinPoints,
+      clusterProperties: config.clusterProperties
+    });
+    this.sourceData.set(sourceId, initialData);
+    if (config.url && !config.prefetchedData) {
+      this.callbacks.onDataLoading?.(layerId);
+      try {
+        const cacheEnabled = config.cache?.enabled ?? true;
+        const cacheTTL = config.cache?.ttl;
+        const result = await this.dataFetcher.fetch(config.url, {
+          skipCache: !cacheEnabled,
+          ttl: cacheTTL
+        });
+        const data = result.data;
+        this.sourceData.set(sourceId, data);
+        const source = this.map.getSource(sourceId);
+        if (source?.setData) {
+          source.setData(data);
+        }
+        this.callbacks.onDataLoaded?.(layerId, data.features.length);
+      } catch (error) {
+        this.callbacks.onDataError?.(layerId, error);
+      }
+    } else if (config.prefetchedData) {
+      this.callbacks.onDataLoaded?.(layerId, initialData.features.length);
+    }
+  }
+  /**
+   * Setup polling and/or streaming for a GeoJSON source
+   */
+  async setupDataUpdates(layerId, sourceId, config) {
+    if (config.stream) {
+      const streamConfig = config.stream;
+      await this.streamManager.connect(layerId, {
+        type: streamConfig.type,
+        url: streamConfig.url || config.url,
+        onData: (data) => {
+          this.handleDataUpdate(sourceId, layerId, data, {
+            strategy: config.refresh?.updateStrategy || config.updateStrategy || "replace",
+            updateKey: config.refresh?.updateKey || config.updateKey,
+            windowSize: config.refresh?.windowSize,
+            windowDuration: config.refresh?.windowDuration,
+            timestampField: config.refresh?.timestampField
+          });
+        },
+        onError: (error) => {
+          this.callbacks.onDataError?.(layerId, error);
+        },
+        reconnect: {
+          enabled: streamConfig.reconnect !== false,
+          maxRetries: streamConfig.reconnectMaxAttempts,
+          initialDelay: streamConfig.reconnectDelay,
+          maxDelay: streamConfig.reconnectMaxDelay
+        },
+        eventTypes: streamConfig.eventTypes,
+        protocols: streamConfig.protocols
+      });
+    }
+    const refreshInterval = config.refresh?.refreshInterval || config.refreshInterval;
+    if (refreshInterval && config.url) {
+      const url = config.url;
+      const cacheEnabled = config.cache?.enabled ?? true;
+      const cacheTTL = config.cache?.ttl;
+      await this.pollingManager.start(layerId, {
+        interval: refreshInterval,
+        onTick: async () => {
+          const result = await this.dataFetcher.fetch(url, {
+            skipCache: !cacheEnabled,
+            ttl: cacheTTL
+          });
+          this.handleDataUpdate(sourceId, layerId, result.data, {
+            strategy: config.refresh?.updateStrategy || config.updateStrategy || "replace",
+            updateKey: config.refresh?.updateKey || config.updateKey,
+            windowSize: config.refresh?.windowSize,
+            windowDuration: config.refresh?.windowDuration,
+            timestampField: config.refresh?.timestampField
+          });
+        },
+        onError: (error) => {
+          this.callbacks.onDataError?.(layerId, error);
+        }
+      });
+    }
+  }
+  /**
+   * Handle incoming data updates with merge strategy
+   */
+  handleDataUpdate(sourceId, layerId, incoming, options) {
+    const existing = this.sourceData.get(sourceId) || {
+      type: "FeatureCollection",
+      features: []
+    };
+    const mergeResult = this.dataMerger.merge(existing, incoming, options);
+    this.sourceData.set(sourceId, mergeResult.data);
+    const source = this.map.getSource(sourceId);
+    if (source?.setData) {
+      source.setData(mergeResult.data);
+    }
+    this.callbacks.onDataLoaded?.(layerId, mergeResult.total);
+  }
+  /**
+   * Pause data refresh for a layer (polling)
+   */
+  pauseRefresh(layerId) {
+    this.pollingManager.pause(layerId);
+  }
+  /**
+   * Resume data refresh for a layer (polling)
+   */
+  resumeRefresh(layerId) {
+    this.pollingManager.resume(layerId);
+  }
+  /**
+   * Force immediate refresh for a layer (polling)
+   */
+  async refreshNow(layerId) {
+    await this.pollingManager.triggerNow(layerId);
+  }
+  /**
+   * Disconnect streaming connection for a layer
+   */
+  disconnectStream(layerId) {
+    this.streamManager.disconnect(layerId);
+  }
+  removeLayer(layerId) {
+    this.pollingManager.stop(layerId);
+    this.streamManager.disconnect(layerId);
+    this.loadingManager.hideLoading(layerId);
+    this.stopRefreshInterval(layerId);
+    const controller = this.abortControllers.get(layerId);
+    if (controller) {
+      controller.abort();
+      this.abortControllers.delete(layerId);
+    }
+    if (this.map.getLayer(layerId)) this.map.removeLayer(layerId);
+    const sourceId = this.layerToSource.get(layerId) || `${layerId}-source`;
+    if (this.map.getSource(sourceId)) this.map.removeSource(sourceId);
+    this.sourceData.delete(sourceId);
+    this.layerToSource.delete(layerId);
+  }
+  setVisibility(layerId, visible) {
+    if (!this.map.getLayer(layerId)) return;
+    this.map.setLayoutProperty(
+      layerId,
+      "visibility",
+      visible ? "visible" : "none"
+    );
+  }
+  updateData(layerId, data) {
+    const sourceId = `${layerId}-source`;
+    const source = this.map.getSource(sourceId);
+    if (source && source.setData) source.setData(data);
+  }
+  /**
+   * @deprecated Legacy refresh method - use PollingManager instead
+   */
+  startRefreshInterval(layer) {
+    if (typeof layer.source !== "object" || layer.source === null) {
+      return;
+    }
+    const sourceObj = layer.source;
+    if (sourceObj.type !== "geojson" || !sourceObj.url || !sourceObj.refreshInterval) {
+      return;
+    }
+    const geojsonSource = layer.source;
+    const interval = setInterval(async () => {
+      const sourceId = `${layer.id}-source`;
+      try {
+        const cacheEnabled = geojsonSource.cache?.enabled ?? true;
+        const cacheTTL = geojsonSource.cache?.ttl;
+        const result = await this.dataFetcher.fetch(geojsonSource.url, {
+          skipCache: !cacheEnabled,
+          ttl: cacheTTL
+        });
+        const data = result.data;
+        this.sourceData.set(sourceId, data);
+        const source = this.map.getSource(sourceId);
+        if (source?.setData) {
+          source.setData(data);
+        }
+        this.callbacks.onDataLoaded?.(layer.id, data.features.length);
+      } catch (error) {
+        this.callbacks.onDataError?.(layer.id, error);
+      }
+    }, geojsonSource.refreshInterval);
+    this.refreshIntervals.set(layer.id, interval);
+  }
+  stopRefreshInterval(layerId) {
+    const interval = this.refreshIntervals.get(layerId);
+    if (interval) {
+      clearInterval(interval);
+      this.refreshIntervals.delete(layerId);
+    }
+  }
+  clearAllIntervals() {
+    for (const interval of this.refreshIntervals.values())
+      clearInterval(interval);
+    this.refreshIntervals.clear();
+  }
+  destroy() {
+    this.pollingManager.destroy();
+    this.streamManager.destroy();
+    this.loadingManager.destroy();
+    this.sourceData.clear();
+    this.layerToSource.clear();
+    this.clearAllIntervals();
+    for (const controller of this.abortControllers.values()) controller.abort();
+    this.abortControllers.clear();
+  }
+};
+
+// src/renderer/popup-builder.ts
+var PopupBuilder = class {
+  /**
+   * Build HTML string from popup content config and feature properties
+   */
+  build(content, properties) {
+    return content.map((item) => {
+      const entries = Object.entries(item);
+      if (entries.length === 0) return "";
+      const entry = entries[0];
+      if (!entry) return "";
+      const [tag, items] = entry;
+      if (!Array.isArray(items)) return "";
+      const innerHTML = items.map((i) => this.buildItem(i, properties)).join("");
+      return `<${tag}>${innerHTML}</${tag}>`;
+    }).join("");
+  }
+  /**
+   * Build a single content item
+   */
+  buildItem(item, properties) {
+    if (item.str) {
+      return this.escapeHtml(item.str);
+    }
+    if (item.property) {
+      const value = properties[item.property];
+      if (value !== void 0 && value !== null) {
+        if (item.format && typeof value === "number") {
+          return this.formatNumber(value, item.format);
+        }
+        return this.escapeHtml(String(value));
+      }
+      return item.else ? this.escapeHtml(item.else) : "";
+    }
+    if (item.href) {
+      const text = item.text || item.href;
+      const target = item.target || "_blank";
+      return `<a href="${this.escapeHtml(
+        item.href
+      )}" target="${target}">${this.escapeHtml(text)}</a>`;
+    }
+    if (item.src) {
+      const alt = item.alt || "";
+      return `<img src="${this.escapeHtml(item.src)}" alt="${this.escapeHtml(
+        alt
+      )}" />`;
+    }
+    return "";
+  }
+  /**
+   * Format a number according to format string
+   */
+  formatNumber(value, format) {
+    const useThousands = format.includes(",");
+    const decimalMatch = format.match(/\.(\d+)/);
+    const decimals = decimalMatch && decimalMatch[1] ? parseInt(decimalMatch[1]) : 0;
+    let result = value.toFixed(decimals);
+    if (useThousands) {
+      const parts = result.split(".");
+      if (parts[0]) {
+        parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+      }
+      result = parts.join(".");
+    }
+    return result;
+  }
+  /**
+   * Escape HTML to prevent XSS
+   */
+  escapeHtml(str) {
+    return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
+  }
+};
+
+// src/renderer/event-handler.ts
+var EventHandler = class {
+  map;
+  callbacks;
+  popupBuilder;
+  activePopup;
+  attachedLayers;
+  boundHandlers;
+  constructor(map, callbacks) {
+    this.map = map;
+    this.callbacks = callbacks || {};
+    this.popupBuilder = new PopupBuilder();
+    this.activePopup = null;
+    this.attachedLayers = /* @__PURE__ */ new Set();
+    this.boundHandlers = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Attach events for a layer based on its interactive config
+   */
+  attachEvents(layer) {
+    if (!layer.interactive) return;
+    const interactive = layer.interactive;
+    const { hover, click } = interactive;
+    const handlers = {};
+    if (hover) {
+      handlers.mouseenter = (e) => {
+        if (hover.cursor) {
+          this.map.getCanvas().style.cursor = hover.cursor;
+        }
+        if (e.features?.[0]) {
+          this.callbacks.onHover?.(layer.id, e.features[0], e.lngLat);
+        }
+      };
+      handlers.mouseleave = () => {
+        this.map.getCanvas().style.cursor = "";
+      };
+      this.map.on("mouseenter", layer.id, handlers.mouseenter);
+      this.map.on("mouseleave", layer.id, handlers.mouseleave);
+    }
+    if (click) {
+      handlers.click = (e) => {
+        const feature = e.features?.[0];
+        if (!feature) return;
+        if (click.popup) {
+          this.showPopup(click.popup, feature, e.lngLat);
+        }
+        this.callbacks.onClick?.(layer.id, feature, e.lngLat);
+      };
+      this.map.on("click", layer.id, handlers.click);
+    }
+    this.boundHandlers.set(layer.id, handlers);
+    this.attachedLayers.add(layer.id);
+  }
+  /**
+   * Show a popup with content
+   */
+  showPopup(content, feature, lngLat) {
+    this.activePopup?.remove();
+    const html = this.popupBuilder.build(content, feature.properties);
+    this.activePopup = new maplibregl2.Popup().setLngLat(lngLat).setHTML(html).addTo(this.map);
+  }
+  /**
+   * Detach events for a layer
+   */
+  detachEvents(layerId) {
+    const handlers = this.boundHandlers.get(layerId);
+    if (!handlers) return;
+    if (handlers.click) {
+      this.map.off("click", layerId, handlers.click);
+    }
+    if (handlers.mouseenter) {
+      this.map.off("mouseenter", layerId, handlers.mouseenter);
+    }
+    if (handlers.mouseleave) {
+      this.map.off("mouseleave", layerId, handlers.mouseleave);
+    }
+    this.boundHandlers.delete(layerId);
+    this.attachedLayers.delete(layerId);
+  }
+  /**
+   * Clean up all event handlers
+   */
+  destroy() {
+    for (const layerId of this.attachedLayers) {
+      this.detachEvents(layerId);
+    }
+    this.activePopup?.remove();
+    this.activePopup = null;
+  }
+};
+
+// src/renderer/legend-builder.ts
+var LegendBuilder = class {
+  /**
+   * Build legend in container from layers
+   */
+  build(container, layers, config) {
+    const el = typeof container === "string" ? document.getElementById(container) : container;
+    if (!el) return;
+    const items = config?.items || this.extractItems(layers);
+    let html = '<div class="maplibre-legend">';
+    if (config?.title) {
+      html += `<div class="legend-title">${this.escapeHtml(config.title)}</div>`;
+    }
+    html += '<div class="legend-items">';
+    for (const item of items) {
+      html += this.renderItem(item);
+    }
+    html += "</div></div>";
+    el.innerHTML = html;
+  }
+  /**
+   * Render a single legend item
+   */
+  renderItem(item) {
+    const shape = item.shape || "square";
+    let symbol = "";
+    switch (shape) {
+      case "circle":
+        symbol = `<span class="legend-symbol circle" style="background:${this.escapeHtml(item.color)}"></span>`;
+        break;
+      case "line":
+        symbol = `<span class="legend-symbol line" style="background:${this.escapeHtml(item.color)}"></span>`;
+        break;
+      case "icon":
+        if (item.icon) {
+          symbol = `<span class="legend-symbol icon">${this.escapeHtml(item.icon)}</span>`;
+        } else {
+          symbol = `<span class="legend-symbol square" style="background:${this.escapeHtml(item.color)}"></span>`;
+        }
+        break;
+      default:
+        symbol = `<span class="legend-symbol square" style="background:${this.escapeHtml(item.color)}"></span>`;
+    }
+    return `<div class="legend-item">${symbol}<span class="legend-label">${this.escapeHtml(item.label)}</span></div>`;
+  }
+  /**
+   * Extract legend items from layers
+   */
+  extractItems(layers) {
+    return layers.filter((l) => l.legend && typeof l.legend === "object").map((l) => l.legend);
+  }
+  /**
+   * Escape HTML to prevent XSS
+   */
+  escapeHtml(str) {
+    return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
+  }
+};
+var ControlsManager = class {
+  map;
+  addedControls;
+  constructor(map) {
+    this.map = map;
+    this.addedControls = [];
+  }
+  /**
+   * Add controls to the map based on configuration
+   */
+  addControls(config) {
+    if (!config) return;
+    if (config.navigation) {
+      const options = typeof config.navigation === "object" ? config.navigation : {};
+      const position = options.position || "top-right";
+      const control = new maplibregl2.NavigationControl();
+      this.map.addControl(control, position);
+      this.addedControls.push(control);
+    }
+    if (config.geolocate) {
+      const options = typeof config.geolocate === "object" ? config.geolocate : {};
+      const position = options.position || "top-right";
+      const control = new maplibregl2.GeolocateControl({
+        positionOptions: { enableHighAccuracy: true },
+        trackUserLocation: true
+      });
+      this.map.addControl(control, position);
+      this.addedControls.push(control);
+    }
+    if (config.scale) {
+      const options = typeof config.scale === "object" ? config.scale : {};
+      const position = options.position || "bottom-left";
+      const control = new maplibregl2.ScaleControl();
+      this.map.addControl(control, position);
+      this.addedControls.push(control);
+    }
+    if (config.fullscreen) {
+      const options = typeof config.fullscreen === "object" ? config.fullscreen : {};
+      const position = options.position || "top-right";
+      const control = new maplibregl2.FullscreenControl();
+      this.map.addControl(control, position);
+      this.addedControls.push(control);
+    }
+  }
+  /**
+   * Remove all controls from the map
+   */
+  removeAllControls() {
+    for (const control of this.addedControls) {
+      this.map.removeControl(control);
+    }
+    this.addedControls = [];
+  }
+};
+
+// src/renderer/map-renderer.ts
+var MapRenderer = class {
+  map;
+  layerManager;
+  eventHandler;
+  legendBuilder;
+  controlsManager;
+  eventListeners;
+  isLoaded;
+  constructor(container, config, layers = [], options = {}) {
+    this.eventListeners = /* @__PURE__ */ new Map();
+    this.isLoaded = false;
+    this.map = new maplibregl2.Map({
+      ...config,
+      container: typeof container === "string" ? container : container,
+      style: config.mapStyle,
+      center: config.center,
+      zoom: config.zoom,
+      pitch: config.pitch ?? 0,
+      bearing: config.bearing ?? 0,
+      interactive: config.interactive ?? true
+    });
+    const layerCallbacks = {
+      onDataLoading: (layerId) => this.emit("layer:data-loading", { layerId }),
+      onDataLoaded: (layerId, featureCount) => this.emit("layer:data-loaded", { layerId, featureCount }),
+      onDataError: (layerId, error) => this.emit("layer:data-error", { layerId, error })
+    };
+    const eventCallbacks = {
+      onClick: (layerId, feature, lngLat) => this.emit("layer:click", { layerId, feature, lngLat }),
+      onHover: (layerId, feature, lngLat) => this.emit("layer:hover", { layerId, feature, lngLat })
+    };
+    this.layerManager = new LayerManager(this.map, layerCallbacks);
+    this.eventHandler = new EventHandler(this.map, eventCallbacks);
+    this.legendBuilder = new LegendBuilder();
+    this.controlsManager = new ControlsManager(this.map);
+    this.map.on("load", () => {
+      this.isLoaded = true;
+      Promise.all(layers.map((layer) => this.addLayer(layer))).then(() => {
+        this.emit("load", void 0);
+        options.onLoad?.();
+      }).catch((error) => {
+        options.onError?.(error);
+      });
+    });
+    this.map.on("error", (e) => {
+      options.onError?.(e.error);
+    });
+  }
+  /**
+   * Get the underlying MapLibre map instance
+   */
+  getMap() {
+    return this.map;
+  }
+  /**
+   * Check if map is loaded
+   */
+  isMapLoaded() {
+    return this.isLoaded;
+  }
+  /**
+   * Add a layer to the map
+   */
+  async addLayer(layer) {
+    await this.layerManager.addLayer(layer);
+    this.eventHandler.attachEvents(layer);
+    this.emit("layer:added", { layerId: layer.id });
+  }
+  /**
+   * Remove a layer from the map
+   */
+  removeLayer(layerId) {
+    this.eventHandler.detachEvents(layerId);
+    this.layerManager.removeLayer(layerId);
+    this.emit("layer:removed", { layerId });
+  }
+  /**
+   * Set layer visibility
+   */
+  setLayerVisibility(layerId, visible) {
+    this.layerManager.setVisibility(layerId, visible);
+  }
+  /**
+   * Update layer data
+   */
+  updateLayerData(layerId, data) {
+    this.layerManager.updateData(layerId, data);
+  }
+  /**
+   * Add controls to the map
+   */
+  addControls(config) {
+    this.controlsManager.addControls(config);
+  }
+  /**
+   * Build legend in container
+   */
+  buildLegend(container, layers, config) {
+    this.legendBuilder.build(container, layers, config);
+  }
+  /**
+   * Get the legend builder instance
+   */
+  getLegendBuilder() {
+    return this.legendBuilder;
+  }
+  /**
+   * Register an event listener
+   */
+  on(event, callback) {
+    if (!this.eventListeners.has(event)) {
+      this.eventListeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.eventListeners.get(event).add(callback);
+  }
+  /**
+   * Unregister an event listener
+   */
+  off(event, callback) {
+    const listeners = this.eventListeners.get(event);
+    if (listeners) {
+      listeners.delete(callback);
+    }
+  }
+  /**
+   * Emit an event
+   */
+  emit(event, data) {
+    const listeners = this.eventListeners.get(event);
+    if (listeners) {
+      for (const callback of listeners) {
+        callback(data);
+      }
+    }
+  }
+  /**
+   * Destroy the map and clean up resources
+   */
+  destroy() {
+    this.eventHandler.destroy();
+    this.layerManager.destroy();
+    this.controlsManager.removeAllControls();
+    this.eventListeners.clear();
+    this.map.remove();
+  }
+};
+var ValidTagNames = [
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "p",
+  "span",
+  "div",
+  "a",
+  "strong",
+  "em",
+  "code",
+  "pre",
+  "img",
+  "iframe",
+  "ul",
+  "ol",
+  "li",
+  "blockquote",
+  "hr",
+  "br"
+];
+var ContentElementSchema = z.object({
+  // Content
+  str: z.string().optional().describe("Static text string"),
+  property: z.string().optional().describe("Dynamic property from context"),
+  else: z.string().optional().describe("Fallback value if property missing"),
+  // Styling
+  classList: z.union([z.string(), z.array(z.string())]).optional().describe("CSS class names (space-separated string or array)"),
+  id: z.string().optional().describe("Element ID attribute"),
+  style: z.string().optional().describe("Inline CSS styles"),
+  // Links
+  href: z.string().url().optional().describe("Link URL"),
+  target: z.string().optional().describe("Link target (_blank, _self, _parent, _top)"),
+  // Media
+  src: z.string().url().optional().describe("Source URL for img or iframe"),
+  alt: z.string().optional().describe("Alternative text for images"),
+  width: z.union([z.string(), z.number()]).optional().describe("Width (pixels or %)"),
+  height: z.union([z.string(), z.number()]).optional().describe("Height (pixels or %)")
+}).passthrough().describe("Content element with styling and properties");
+var ContentItemSchema = z.record(z.enum(ValidTagNames), z.array(ContentElementSchema)).describe("Content item mapping tag to elements");
+var ContentBlockSchema = z.object({
+  type: z.literal("content").describe("Block type"),
+  id: z.string().optional().describe("Unique block identifier"),
+  className: z.string().optional().describe("CSS class name for the block container"),
+  style: z.string().optional().describe("Inline CSS styles for the block container"),
+  content: z.array(ContentItemSchema).describe("Array of content items to render")
+}).describe("Content block for rich text and media");
+var LongitudeSchema = z.number().min(-180, "Longitude must be >= -180").max(180, "Longitude must be <= 180").describe("Longitude in degrees (-180 to 180)");
+var LatitudeSchema = z.number().min(-90, "Latitude must be >= -90").max(90, "Latitude must be <= 90").describe("Latitude in degrees (-90 to 90)");
+var LngLatSchema = z.tuple([LongitudeSchema, LatitudeSchema]).describe("Geographic coordinates as [longitude, latitude]");
+var LngLatBoundsSchema = z.tuple([
+  LongitudeSchema,
+  // west
+  LatitudeSchema,
+  // south
+  LongitudeSchema,
+  // east
+  LatitudeSchema
+  // north
+]).describe("Bounding box as [west, south, east, north]");
+var ColorSchema = z.string().refine(
+  (val) => {
+    if (val.startsWith("#")) {
+      return /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(val);
+    }
+    if (val.startsWith("rgb")) {
+      return /^rgba?\s*\([^)]+\)$/.test(val);
+    }
+    if (val.startsWith("hsl")) {
+      return /^hsla?\s*\([^)]+\)$/.test(val);
+    }
+    return true;
+  },
+  {
+    message: "Invalid color format. Use hex (#rgb, #rrggbb), rgb(), rgba(), hsl(), hsla(), or named colors."
+  }
+).describe("CSS color value");
+var ExpressionSchema = z.array(z.any()).refine((val) => val.length > 0 && typeof val[0] === "string", {
+  message: 'Expression must be an array starting with a string operator (e.g., ["get", "property"])'
+}).describe("MapLibre expression for data-driven styling");
+var NumberOrExpressionSchema = z.union([z.number(), ExpressionSchema]).describe("Number value or MapLibre expression");
+var ColorOrExpressionSchema = z.union([ColorSchema, ExpressionSchema]).describe("Color value or MapLibre expression");
+var ZoomLevelSchema = z.number().min(0, "Zoom level must be >= 0").max(24, "Zoom level must be <= 24").describe("Map zoom level (0-24)");
+var StreamConfigSchema = z.object({
+  type: z.enum(["websocket", "sse"]).describe("Streaming connection type"),
+  url: z.string().url().optional().describe("WebSocket or SSE endpoint URL"),
+  reconnect: z.boolean().default(true).describe("Automatically reconnect on disconnect"),
+  reconnectMaxAttempts: z.number().min(0).default(10).describe("Maximum number of reconnection attempts"),
+  reconnectDelay: z.number().min(100).default(1e3).describe("Initial delay in milliseconds before reconnecting"),
+  reconnectMaxDelay: z.number().min(1e3).default(3e4).describe("Maximum delay in milliseconds for exponential backoff"),
+  eventTypes: z.array(z.string()).optional().describe("Event types to listen for (SSE only)"),
+  protocols: z.union([z.string(), z.array(z.string())]).optional().describe("WebSocket sub-protocols (WebSocket only)")
+});
+var LoadingConfigSchema = z.object({
+  enabled: z.boolean().default(false).describe("Enable loading UI overlays"),
+  message: z.string().optional().describe("Custom loading message to display"),
+  showErrorOverlay: z.boolean().default(true).describe("Show error overlay on fetch failure")
+});
+var CacheConfigSchema = z.object({
+  enabled: z.boolean().default(true).describe("Enable HTTP caching"),
+  ttl: z.number().positive().optional().describe("Cache TTL in milliseconds (overrides default)")
+});
+var RefreshConfigSchema = z.object({
+  refreshInterval: z.number().min(1e3).optional().describe("Polling interval in milliseconds (minimum 1000ms)"),
+  updateStrategy: z.enum(["replace", "merge", "append-window"]).default("replace").describe("How to merge incoming data with existing data"),
+  updateKey: z.string().optional().describe("Property key for merge strategy (required for merge)"),
+  windowSize: z.number().positive().optional().describe("Maximum features to keep (append-window)"),
+  windowDuration: z.number().positive().optional().describe("Maximum age in milliseconds (append-window)"),
+  timestampField: z.string().optional().describe("Property field containing timestamp (append-window)")
+}).refine((data) => !(data.updateStrategy === "merge" && !data.updateKey), {
+  message: "updateKey is required when updateStrategy is 'merge'"
+});
+var GeoJSONSourceSchema = z.object({
+  type: z.literal("geojson").describe("Source type"),
+  url: z.string().url().optional().describe("URL to fetch GeoJSON data"),
+  data: z.any().optional().describe("Inline GeoJSON object"),
+  prefetchedData: z.any().optional().describe("Pre-fetched data from build time"),
+  fetchStrategy: z.enum(["runtime", "build", "hybrid"]).default("runtime").describe("When to fetch data: runtime (default), build, or hybrid"),
+  stream: StreamConfigSchema.optional().describe(
+    "WebSocket/SSE streaming configuration"
+  ),
+  refresh: RefreshConfigSchema.optional().describe(
+    "Polling refresh configuration"
+  ),
+  // Legacy support for direct refresh properties
+  refreshInterval: z.number().min(1e3).optional().describe("Polling interval in milliseconds (legacy, use refresh.refreshInterval)"),
+  updateStrategy: z.enum(["replace", "merge", "append-window"]).optional().describe("Update strategy (legacy, use refresh.updateStrategy)"),
+  updateKey: z.string().optional().describe("Update key (legacy, use refresh.updateKey)"),
+  loading: LoadingConfigSchema.optional().describe(
+    "Loading UI configuration"
+  ),
+  cache: CacheConfigSchema.optional().describe("Cache configuration"),
+  // MapLibre clustering options
+  cluster: z.boolean().optional().describe("Enable point clustering"),
+  clusterRadius: z.number().int().min(0).default(50).describe("Cluster radius in pixels"),
+  clusterMaxZoom: z.number().min(0).max(24).optional().describe("Maximum zoom level to cluster points"),
+  clusterMinPoints: z.number().int().min(2).optional().describe("Minimum points to form a cluster"),
+  clusterProperties: z.record(z.any()).optional().describe("Aggregate cluster properties"),
+  // Additional MapLibre options (passthrough)
+  tolerance: z.number().optional(),
+  buffer: z.number().optional(),
+  lineMetrics: z.boolean().optional(),
+  generateId: z.boolean().optional(),
+  promoteId: z.union([z.string(), z.record(z.string())]).optional(),
+  attribution: z.string().optional()
+}).passthrough().refine((data) => data.url || data.data || data.prefetchedData, {
+  message: 'GeoJSON source requires at least one of: url, data, or prefetchedData. Use "url" to fetch from an endpoint, "data" for inline GeoJSON, or "prefetchedData" for build-time fetched data.'
+});
+var VectorSourceSchema = z.object({
+  type: z.literal("vector").describe("Source type"),
+  url: z.string().url().optional().describe("TileJSON URL"),
+  tiles: z.array(z.string().url()).optional().describe("Tile URL template array"),
+  minzoom: z.number().min(0).max(24).optional().describe("Minimum zoom level"),
+  maxzoom: z.number().min(0).max(24).optional().describe("Maximum zoom level"),
+  bounds: z.tuple([z.number(), z.number(), z.number(), z.number()]).optional().describe("Bounding box [west, south, east, north]"),
+  scheme: z.enum(["xyz", "tms"]).optional().describe("Tile coordinate scheme"),
+  attribution: z.string().optional().describe("Attribution text"),
+  promoteId: z.union([z.string(), z.record(z.string())]).optional(),
+  volatile: z.boolean().optional()
+}).passthrough().refine((data) => data.url || data.tiles, {
+  message: 'Vector source requires either "url" (TileJSON) or "tiles" (tile URL array). Provide at least one of these properties.'
+});
+var RasterSourceSchema = z.object({
+  type: z.literal("raster").describe("Source type"),
+  url: z.string().url().optional().describe("TileJSON URL"),
+  tiles: z.array(z.string().url()).optional().describe("Tile URL template array"),
+  tileSize: z.number().int().min(1).default(512).describe("Tile size in pixels"),
+  minzoom: z.number().min(0).max(24).optional().describe("Minimum zoom level"),
+  maxzoom: z.number().min(0).max(24).optional().describe("Maximum zoom level"),
+  bounds: z.tuple([z.number(), z.number(), z.number(), z.number()]).optional().describe("Bounding box [west, south, east, north]"),
+  scheme: z.enum(["xyz", "tms"]).optional().describe("Tile coordinate scheme"),
+  attribution: z.string().optional().describe("Attribution text"),
+  volatile: z.boolean().optional()
+}).passthrough().refine((data) => data.url || data.tiles, {
+  message: 'Raster source requires either "url" (TileJSON) or "tiles" (tile URL array). Provide at least one of these properties.'
+});
+var ImageSourceSchema = z.object({
+  type: z.literal("image").describe("Source type"),
+  url: z.string().url().describe("Image URL"),
+  coordinates: z.tuple([LngLatSchema, LngLatSchema, LngLatSchema, LngLatSchema]).describe(
+    "Four corner coordinates [topLeft, topRight, bottomRight, bottomLeft]"
+  )
+}).passthrough();
+var VideoSourceSchema = z.object({
+  type: z.literal("video").describe("Source type"),
+  urls: z.array(z.string().url()).min(1).describe("Array of video URLs for browser compatibility"),
+  coordinates: z.tuple([LngLatSchema, LngLatSchema, LngLatSchema, LngLatSchema]).describe(
+    "Four corner coordinates [topLeft, topRight, bottomRight, bottomLeft]"
+  )
+}).passthrough();
+var LayerSourceSchema = z.union([
+  GeoJSONSourceSchema,
+  VectorSourceSchema,
+  RasterSourceSchema,
+  ImageSourceSchema,
+  VideoSourceSchema
+]);
+
+// src/schemas/layer.schema.ts
+var PopupContentItemSchema = z.object({
+  str: z.string().optional().describe("Static text string"),
+  property: z.string().optional().describe("Feature property name"),
+  else: z.string().optional().describe("Fallback value if property missing"),
+  format: z.string().optional().describe('Number format string (e.g., ",.0f")'),
+  href: z.string().url().optional().describe("Link URL"),
+  text: z.string().optional().describe("Link text"),
+  src: z.string().url().optional().describe("Image/iframe source"),
+  alt: z.string().optional().describe("Image alt text")
+}).passthrough().describe("Popup content item with static or dynamic values");
+var PopupContentSchema = z.array(z.record(z.array(PopupContentItemSchema))).describe("Popup content structure as array of HTML elements");
+var InteractiveConfigSchema = z.object({
+  hover: z.object({
+    cursor: z.string().optional().describe('CSS cursor style (e.g., "pointer")'),
+    highlight: z.boolean().optional().describe("Highlight feature on hover")
+  }).optional().describe("Hover behavior"),
+  click: z.object({
+    popup: PopupContentSchema.optional().describe(
+      "Popup content to display"
+    ),
+    action: z.string().optional().describe("Custom action name to trigger"),
+    flyTo: z.object({
+      center: z.tuple([z.number(), z.number()]).optional(),
+      zoom: ZoomLevelSchema.optional(),
+      duration: z.number().optional()
+    }).optional().describe("Fly to location on click")
+  }).optional().describe("Click behavior"),
+  mouseenter: z.object({
+    action: z.string().optional().describe("Custom action on mouse enter")
+  }).optional(),
+  mouseleave: z.object({
+    action: z.string().optional().describe("Custom action on mouse leave")
+  }).optional()
+}).optional().describe("Interactive event configuration");
+var LegendItemSchema = z.object({
+  color: z.string().describe("CSS color value"),
+  label: z.string().describe("Legend label text"),
+  shape: z.enum(["circle", "square", "line", "icon"]).default("square").describe("Symbol shape"),
+  icon: z.string().optional().describe("Icon name or URL (for shape: icon)")
+}).describe("Legend item configuration");
+var BaseLayerPropertiesSchema = z.object({
+  id: z.string().describe("Unique layer identifier"),
+  label: z.string().optional().describe("Human-readable layer label"),
+  source: z.union([LayerSourceSchema, z.string()]).describe("Layer source (inline definition or source ID reference)"),
+  "source-layer": z.string().optional().describe("Source layer name (for vector sources)"),
+  minzoom: ZoomLevelSchema.optional().describe(
+    "Minimum zoom level to show layer"
+  ),
+  maxzoom: ZoomLevelSchema.optional().describe(
+    "Maximum zoom level to show layer"
+  ),
+  filter: ExpressionSchema.optional().describe("MapLibre filter expression"),
+  visible: z.boolean().default(true).describe("Initial visibility state"),
+  toggleable: z.boolean().default(true).describe("Allow users to toggle visibility"),
+  before: z.string().optional().describe("Layer ID to insert this layer before"),
+  interactive: InteractiveConfigSchema.describe(
+    "Interactive event configuration"
+  ),
+  legend: LegendItemSchema.optional().describe("Legend configuration"),
+  metadata: z.record(z.any()).optional().describe("Custom metadata")
+});
+var CircleLayerSchema = BaseLayerPropertiesSchema.extend({
+  type: z.literal("circle").describe("Layer type"),
+  paint: z.object({
+    "circle-radius": NumberOrExpressionSchema.optional(),
+    "circle-color": ColorOrExpressionSchema.optional(),
+    "circle-blur": NumberOrExpressionSchema.optional(),
+    "circle-opacity": NumberOrExpressionSchema.optional(),
+    "circle-stroke-width": NumberOrExpressionSchema.optional(),
+    "circle-stroke-color": ColorOrExpressionSchema.optional(),
+    "circle-stroke-opacity": NumberOrExpressionSchema.optional(),
+    "circle-pitch-scale": z.enum(["map", "viewport"]).optional(),
+    "circle-pitch-alignment": z.enum(["map", "viewport"]).optional(),
+    "circle-translate": z.tuple([z.number(), z.number()]).optional(),
+    "circle-translate-anchor": z.enum(["map", "viewport"]).optional()
+  }).passthrough().optional().describe("Circle paint properties"),
+  layout: z.object({}).passthrough().optional().describe("Circle layout properties")
+}).passthrough();
+var LineLayerSchema = BaseLayerPropertiesSchema.extend({
+  type: z.literal("line").describe("Layer type"),
+  paint: z.object({
+    "line-opacity": NumberOrExpressionSchema.optional(),
+    "line-color": ColorOrExpressionSchema.optional(),
+    "line-width": NumberOrExpressionSchema.optional(),
+    "line-gap-width": NumberOrExpressionSchema.optional(),
+    "line-offset": NumberOrExpressionSchema.optional(),
+    "line-blur": NumberOrExpressionSchema.optional(),
+    "line-dasharray": z.array(z.number()).optional(),
+    "line-pattern": z.string().optional(),
+    "line-gradient": ColorOrExpressionSchema.optional(),
+    "line-translate": z.tuple([z.number(), z.number()]).optional(),
+    "line-translate-anchor": z.enum(["map", "viewport"]).optional()
+  }).passthrough().optional().describe("Line paint properties"),
+  layout: z.object({
+    "line-cap": z.enum(["butt", "round", "square"]).optional(),
+    "line-join": z.enum(["bevel", "round", "miter"]).optional(),
+    "line-miter-limit": z.number().optional(),
+    "line-round-limit": z.number().optional(),
+    "line-sort-key": NumberOrExpressionSchema.optional()
+  }).passthrough().optional().describe("Line layout properties")
+}).passthrough();
+var FillLayerSchema = BaseLayerPropertiesSchema.extend({
+  type: z.literal("fill").describe("Layer type"),
+  paint: z.object({
+    "fill-antialias": z.boolean().optional(),
+    "fill-opacity": NumberOrExpressionSchema.optional(),
+    "fill-color": ColorOrExpressionSchema.optional(),
+    "fill-outline-color": ColorOrExpressionSchema.optional(),
+    "fill-translate": z.tuple([z.number(), z.number()]).optional(),
+    "fill-translate-anchor": z.enum(["map", "viewport"]).optional(),
+    "fill-pattern": z.string().optional()
+  }).passthrough().optional().describe("Fill paint properties"),
+  layout: z.object({
+    "fill-sort-key": NumberOrExpressionSchema.optional()
+  }).passthrough().optional().describe("Fill layout properties")
+}).passthrough();
+var SymbolLayerSchema = BaseLayerPropertiesSchema.extend({
+  type: z.literal("symbol").describe("Layer type"),
+  layout: z.object({
+    "symbol-placement": z.enum(["point", "line", "line-center"]).optional(),
+    "symbol-spacing": z.number().optional(),
+    "symbol-avoid-edges": z.boolean().optional(),
+    "symbol-sort-key": NumberOrExpressionSchema.optional(),
+    "symbol-z-order": z.enum(["auto", "viewport-y", "source"]).optional(),
+    "icon-allow-overlap": z.boolean().optional(),
+    "icon-ignore-placement": z.boolean().optional(),
+    "icon-optional": z.boolean().optional(),
+    "icon-rotation-alignment": z.enum(["map", "viewport", "auto"]).optional(),
+    "icon-size": NumberOrExpressionSchema.optional(),
+    "icon-text-fit": z.enum(["none", "width", "height", "both"]).optional(),
+    "icon-text-fit-padding": z.tuple([z.number(), z.number(), z.number(), z.number()]).optional(),
+    "icon-image": z.union([z.string(), ExpressionSchema]).optional(),
+    "icon-rotate": NumberOrExpressionSchema.optional(),
+    "icon-padding": z.number().optional(),
+    "icon-keep-upright": z.boolean().optional(),
+    "icon-offset": z.tuple([z.number(), z.number()]).optional(),
+    "icon-anchor": z.enum([
+      "center",
+      "left",
+      "right",
+      "top",
+      "bottom",
+      "top-left",
+      "top-right",
+      "bottom-left",
+      "bottom-right"
+    ]).optional(),
+    "icon-pitch-alignment": z.enum(["map", "viewport", "auto"]).optional(),
+    "text-pitch-alignment": z.enum(["map", "viewport", "auto"]).optional(),
+    "text-rotation-alignment": z.enum(["map", "viewport", "auto"]).optional(),
+    "text-field": z.union([z.string(), ExpressionSchema]).optional(),
+    "text-font": z.array(z.string()).optional(),
+    "text-size": NumberOrExpressionSchema.optional(),
+    "text-max-width": NumberOrExpressionSchema.optional(),
+    "text-line-height": z.number().optional(),
+    "text-letter-spacing": z.number().optional(),
+    "text-justify": z.enum(["auto", "left", "center", "right"]).optional(),
+    "text-radial-offset": z.number().optional(),
+    "text-variable-anchor": z.array(
+      z.enum([
+        "center",
+        "left",
+        "right",
+        "top",
+        "bottom",
+        "top-left",
+        "top-right",
+        "bottom-left",
+        "bottom-right"
+      ])
+    ).optional(),
+    "text-anchor": z.enum([
+      "center",
+      "left",
+      "right",
+      "top",
+      "bottom",
+      "top-left",
+      "top-right",
+      "bottom-left",
+      "bottom-right"
+    ]).optional(),
+    "text-max-angle": z.number().optional(),
+    "text-rotate": NumberOrExpressionSchema.optional(),
+    "text-padding": z.number().optional(),
+    "text-keep-upright": z.boolean().optional(),
+    "text-transform": z.enum(["none", "uppercase", "lowercase"]).optional(),
+    "text-offset": z.tuple([z.number(), z.number()]).optional(),
+    "text-allow-overlap": z.boolean().optional(),
+    "text-ignore-placement": z.boolean().optional(),
+    "text-optional": z.boolean().optional()
+  }).passthrough().optional().describe("Symbol layout properties"),
+  paint: z.object({
+    "icon-opacity": NumberOrExpressionSchema.optional(),
+    "icon-color": ColorOrExpressionSchema.optional(),
+    "icon-halo-color": ColorOrExpressionSchema.optional(),
+    "icon-halo-width": NumberOrExpressionSchema.optional(),
+    "icon-halo-blur": NumberOrExpressionSchema.optional(),
+    "icon-translate": z.tuple([z.number(), z.number()]).optional(),
+    "icon-translate-anchor": z.enum(["map", "viewport"]).optional(),
+    "text-opacity": NumberOrExpressionSchema.optional(),
+    "text-color": ColorOrExpressionSchema.optional(),
+    "text-halo-color": ColorOrExpressionSchema.optional(),
+    "text-halo-width": NumberOrExpressionSchema.optional(),
+    "text-halo-blur": NumberOrExpressionSchema.optional(),
+    "text-translate": z.tuple([z.number(), z.number()]).optional(),
+    "text-translate-anchor": z.enum(["map", "viewport"]).optional()
+  }).passthrough().optional().describe("Symbol paint properties")
+}).passthrough();
+var RasterLayerSchema = BaseLayerPropertiesSchema.extend({
+  type: z.literal("raster").describe("Layer type"),
+  paint: z.object({
+    "raster-opacity": NumberOrExpressionSchema.optional(),
+    "raster-hue-rotate": NumberOrExpressionSchema.optional(),
+    "raster-brightness-min": NumberOrExpressionSchema.optional(),
+    "raster-brightness-max": NumberOrExpressionSchema.optional(),
+    "raster-saturation": NumberOrExpressionSchema.optional(),
+    "raster-contrast": NumberOrExpressionSchema.optional(),
+    "raster-resampling": z.enum(["linear", "nearest"]).optional(),
+    "raster-fade-duration": z.number().optional()
+  }).passthrough().optional().describe("Raster paint properties"),
+  layout: z.object({}).passthrough().optional().describe("Raster layout properties")
+}).passthrough();
+var FillExtrusionLayerSchema = BaseLayerPropertiesSchema.extend({
+  type: z.literal("fill-extrusion").describe("Layer type"),
+  paint: z.object({
+    "fill-extrusion-opacity": NumberOrExpressionSchema.optional(),
+    "fill-extrusion-color": ColorOrExpressionSchema.optional(),
+    "fill-extrusion-translate": z.tuple([z.number(), z.number()]).optional(),
+    "fill-extrusion-translate-anchor": z.enum(["map", "viewport"]).optional(),
+    "fill-extrusion-pattern": z.string().optional(),
+    "fill-extrusion-height": NumberOrExpressionSchema.optional(),
+    "fill-extrusion-base": NumberOrExpressionSchema.optional(),
+    "fill-extrusion-vertical-gradient": z.boolean().optional()
+  }).passthrough().optional().describe("Fill extrusion paint properties"),
+  layout: z.object({}).passthrough().optional().describe("Fill extrusion layout properties")
+}).passthrough();
+var HeatmapLayerSchema = BaseLayerPropertiesSchema.extend({
+  type: z.literal("heatmap").describe("Layer type"),
+  paint: z.object({
+    "heatmap-radius": NumberOrExpressionSchema.optional(),
+    "heatmap-weight": NumberOrExpressionSchema.optional(),
+    "heatmap-intensity": NumberOrExpressionSchema.optional(),
+    "heatmap-color": ColorOrExpressionSchema.optional(),
+    "heatmap-opacity": NumberOrExpressionSchema.optional()
+  }).passthrough().optional().describe("Heatmap paint properties"),
+  layout: z.object({}).passthrough().optional().describe("Heatmap layout properties")
+}).passthrough();
+var HillshadeLayerSchema = BaseLayerPropertiesSchema.extend({
+  type: z.literal("hillshade").describe("Layer type"),
+  paint: z.object({
+    "hillshade-illumination-direction": z.number().optional(),
+    "hillshade-illumination-anchor": z.enum(["map", "viewport"]).optional(),
+    "hillshade-exaggeration": NumberOrExpressionSchema.optional(),
+    "hillshade-shadow-color": ColorOrExpressionSchema.optional(),
+    "hillshade-highlight-color": ColorOrExpressionSchema.optional(),
+    "hillshade-accent-color": ColorOrExpressionSchema.optional()
+  }).passthrough().optional().describe("Hillshade paint properties"),
+  layout: z.object({}).passthrough().optional().describe("Hillshade layout properties")
+}).passthrough();
+var BackgroundLayerSchema = z.object({
+  id: z.string().describe("Unique layer identifier"),
+  type: z.literal("background").describe("Layer type"),
+  paint: z.object({
+    "background-color": ColorOrExpressionSchema.optional(),
+    "background-pattern": z.string().optional(),
+    "background-opacity": NumberOrExpressionSchema.optional()
+  }).passthrough().optional().describe("Background paint properties"),
+  layout: z.object({}).passthrough().optional().describe("Background layout properties"),
+  metadata: z.record(z.any()).optional().describe("Custom metadata")
+}).passthrough();
+var LayerSchema = z.union([
+  CircleLayerSchema,
+  LineLayerSchema,
+  FillLayerSchema,
+  SymbolLayerSchema,
+  RasterLayerSchema,
+  FillExtrusionLayerSchema,
+  HeatmapLayerSchema,
+  HillshadeLayerSchema,
+  BackgroundLayerSchema
+]);
+var LayerReferenceSchema = z.object({
+  $ref: z.string().describe('Reference to global layer (e.g., "#/layers/bikeLayer")')
+}).describe("Layer reference");
+var LayerOrReferenceSchema = z.union([
+  LayerSchema,
+  LayerReferenceSchema
+]);
+
+// src/schemas/map.schema.ts
+var ControlPositionSchema = z.enum([
+  "top-left",
+  "top-right",
+  "bottom-left",
+  "bottom-right"
+]);
+var ControlConfigSchema = z.union([
+  z.boolean(),
+  z.object({
+    enabled: z.boolean().describe("Whether control is enabled"),
+    position: ControlPositionSchema.optional().describe("Control position")
+  })
+]);
+var ControlsConfigSchema = z.object({
+  navigation: ControlConfigSchema.optional().describe(
+    "Navigation controls (zoom, rotation)"
+  ),
+  geolocate: ControlConfigSchema.optional().describe("Geolocation control"),
+  scale: ControlConfigSchema.optional().describe("Scale control"),
+  fullscreen: ControlConfigSchema.optional().describe("Fullscreen control"),
+  attribution: ControlConfigSchema.optional().describe("Attribution control")
+}).describe("Map controls configuration");
+var LegendConfigSchema = z.object({
+  position: ControlPositionSchema.default("top-left").describe("Legend position"),
+  title: z.string().optional().describe("Legend title"),
+  collapsed: z.boolean().default(false).describe("Start collapsed"),
+  items: z.array(
+    z.object({
+      color: z.string().describe("Item color"),
+      label: z.string().describe("Item label"),
+      shape: z.enum(["circle", "square", "line", "icon"]).default("square").describe("Symbol shape"),
+      icon: z.string().optional().describe("Icon name/URL (for shape: icon)")
+    })
+  ).optional().describe("Custom legend items (overrides layer legends)")
+}).describe("Legend configuration");
+var MapConfigSchema = z.object({
+  // Required
+  center: LngLatSchema.describe("Initial map center [longitude, latitude]"),
+  zoom: ZoomLevelSchema.describe("Initial zoom level (0-24)"),
+  mapStyle: z.union([z.string().url(), z.any()]).describe("MapLibre style URL or style object"),
+  // View
+  pitch: z.number().min(0).max(85).default(0).describe("Camera pitch angle in degrees (0-85)"),
+  bearing: z.number().min(-180).max(180).default(0).describe("Camera bearing (rotation) in degrees (-180 to 180)"),
+  bounds: z.union([LngLatBoundsSchema, z.array(z.number())]).optional().describe("Fit map to bounds"),
+  // Constraints
+  minZoom: ZoomLevelSchema.optional().describe("Minimum zoom level"),
+  maxZoom: ZoomLevelSchema.optional().describe("Maximum zoom level"),
+  minPitch: z.number().min(0).max(85).optional().describe("Minimum pitch"),
+  maxPitch: z.number().min(0).max(85).optional().describe("Maximum pitch"),
+  maxBounds: LngLatBoundsSchema.optional().describe(
+    "Maximum geographic bounds"
+  ),
+  // Interaction
+  interactive: z.boolean().default(true).describe("Enable map interaction"),
+  scrollZoom: z.boolean().optional().describe("Enable scroll to zoom"),
+  boxZoom: z.boolean().optional().describe("Enable box zoom (shift+drag)"),
+  dragRotate: z.boolean().optional().describe("Enable drag to rotate"),
+  dragPan: z.boolean().optional().describe("Enable drag to pan"),
+  keyboard: z.boolean().optional().describe("Enable keyboard shortcuts"),
+  doubleClickZoom: z.boolean().optional().describe("Enable double-click zoom"),
+  touchZoomRotate: z.boolean().optional().describe("Enable touch zoom/rotate"),
+  touchPitch: z.boolean().optional().describe("Enable touch pitch"),
+  // Display
+  hash: z.boolean().optional().describe("Sync map state with URL hash"),
+  attributionControl: z.boolean().optional().describe("Show attribution control"),
+  logoPosition: ControlPositionSchema.optional().describe(
+    "MapLibre logo position"
+  ),
+  fadeDuration: z.number().optional().describe("Fade duration in milliseconds"),
+  crossSourceCollisions: z.boolean().optional().describe("Check for cross-source collisions"),
+  // Rendering
+  antialias: z.boolean().optional().describe("Enable antialiasing"),
+  refreshExpiredTiles: z.boolean().optional().describe("Refresh expired tiles"),
+  renderWorldCopies: z.boolean().optional().describe("Render multiple world copies"),
+  locale: z.record(z.string()).optional().describe("Localization strings"),
+  // Performance
+  maxTileCacheSize: z.number().optional().describe("Maximum tiles to cache"),
+  localIdeographFontFamily: z.string().optional().describe("Font for CJK characters"),
+  trackResize: z.boolean().optional().describe("Track container resize"),
+  preserveDrawingBuffer: z.boolean().optional().describe("Preserve drawing buffer"),
+  failIfMajorPerformanceCaveat: z.boolean().optional().describe("Fail if major performance caveat")
+}).passthrough().describe("Map configuration with MapLibre options");
+var MapBlockSchema = z.object({
+  type: z.literal("map").describe("Block type"),
+  id: z.string().describe("Unique block identifier"),
+  className: z.string().optional().describe("CSS class name for container"),
+  style: z.string().optional().describe("Inline CSS styles for container"),
+  config: MapConfigSchema.describe("Map configuration"),
+  layers: z.array(LayerOrReferenceSchema).default([]).describe("Map layers"),
+  controls: ControlsConfigSchema.optional().describe("Map controls"),
+  legend: LegendConfigSchema.optional().describe("Legend configuration")
+}).describe("Standard map block");
+var MapFullPageBlockSchema = z.object({
+  type: z.literal("map-fullpage").describe("Block type"),
+  id: z.string().describe("Unique block identifier"),
+  className: z.string().optional().describe("CSS class name for container"),
+  style: z.string().optional().describe("Inline CSS styles for container"),
+  config: MapConfigSchema.describe("Map configuration"),
+  layers: z.array(LayerOrReferenceSchema).default([]).describe("Map layers"),
+  controls: ControlsConfigSchema.optional().describe("Map controls"),
+  legend: LegendConfigSchema.optional().describe("Legend configuration")
+}).describe("Full-page map block");
+var ChapterActionSchema = z.object({
+  action: z.enum([
+    "setFilter",
+    "setPaintProperty",
+    "setLayoutProperty",
+    "flyTo",
+    "easeTo",
+    "fitBounds",
+    "custom"
+  ]).describe("Action type"),
+  layer: z.string().optional().describe("Target layer ID"),
+  property: z.string().optional().describe("Property name (for setPaintProperty/setLayoutProperty)"),
+  value: z.any().optional().describe("Property value"),
+  filter: ExpressionSchema.nullable().optional().describe("Filter expression (for setFilter, null to clear)"),
+  bounds: z.array(z.number()).optional().describe("Bounds array (for fitBounds)"),
+  options: z.record(z.any()).optional().describe("Additional options")
+}).describe("Chapter action for map state changes");
+var ChapterLayersSchema = z.object({
+  show: z.array(z.string()).default([]).describe("Layer IDs to show"),
+  hide: z.array(z.string()).default([]).describe("Layer IDs to hide")
+}).describe("Chapter layer visibility configuration");
+var ChapterSchema = z.object({
+  // Required
+  id: z.string().describe("Unique chapter identifier"),
+  title: z.string().describe("Chapter title"),
+  center: LngLatSchema.describe("Map center [longitude, latitude]"),
+  zoom: z.number().describe("Zoom level"),
+  // Content
+  description: z.string().optional().describe("Chapter description (HTML/markdown supported)"),
+  image: z.string().url().optional().describe("Hero image URL"),
+  video: z.string().url().optional().describe("Video URL"),
+  // Camera
+  pitch: z.number().min(0).max(85).default(0).describe("Camera pitch angle (0-85)"),
+  bearing: z.number().min(-180).max(180).default(0).describe("Camera bearing (-180 to 180)"),
+  speed: z.number().min(0).max(2).default(0.6).describe("Animation speed multiplier (0-2)"),
+  curve: z.number().min(0).max(2).default(1).describe("Animation curve (0=linear, 1=default, 2=steep)"),
+  animation: z.enum(["flyTo", "easeTo", "jumpTo"]).default("flyTo").describe("Animation type"),
+  // Rotation animation
+  rotateAnimation: z.boolean().optional().describe("Enable continuous rotation animation"),
+  spinGlobe: z.boolean().optional().describe("Spin globe animation (for low zoom levels)"),
+  // Layout
+  alignment: z.enum(["left", "right", "center", "full"]).default("center").describe("Content alignment"),
+  hidden: z.boolean().default(false).describe("Hide chapter content (map-only)"),
+  // Layers
+  layers: ChapterLayersSchema.optional().describe("Layer visibility control"),
+  // Actions
+  onChapterEnter: z.array(ChapterActionSchema).default([]).describe("Actions when entering chapter"),
+  onChapterExit: z.array(ChapterActionSchema).default([]).describe("Actions when exiting chapter"),
+  // Custom
+  callback: z.string().optional().describe("Custom callback function name")
+}).describe("Scrollytelling chapter");
+var ScrollytellingBlockSchema = z.object({
+  type: z.literal("scrollytelling").describe("Block type"),
+  id: z.string().describe("Unique block identifier"),
+  className: z.string().optional().describe("CSS class name for container"),
+  style: z.string().optional().describe("Inline CSS styles for container"),
+  // Base config
+  config: MapConfigSchema.describe("Base map configuration"),
+  // Theme
+  theme: z.enum(["light", "dark"]).default("light").describe("Visual theme"),
+  // Markers
+  showMarkers: z.boolean().default(false).describe("Show chapter markers on map"),
+  markerColor: z.string().default("#3FB1CE").describe("Chapter marker color"),
+  // Layers (persistent across all chapters)
+  layers: z.array(LayerOrReferenceSchema).default([]).describe("Persistent layers (visible throughout story)"),
+  // Chapters
+  chapters: z.array(ChapterSchema).min(1, "At least one chapter is required for scrollytelling").describe("Story chapters"),
+  // Footer
+  footer: z.string().optional().describe("Footer content (HTML)")
+}).describe("Scrollytelling block for narrative map stories");
+
+// src/schemas/page.schema.ts
+var MixedBlockSchema = z.lazy(
+  () => z.object({
+    type: z.literal("mixed").describe("Block type"),
+    id: z.string().optional().describe("Unique block identifier"),
+    className: z.string().optional().describe("CSS class name for container"),
+    style: z.string().optional().describe("Inline CSS styles for container"),
+    layout: z.enum(["row", "column", "grid"]).default("row").describe("Layout direction"),
+    gap: z.string().optional().describe("Gap between blocks (CSS gap property)"),
+    blocks: z.array(BlockSchema).describe("Child blocks")
+  }).describe("Mixed block for combining multiple block types")
+);
+var BlockSchema = z.union([
+  ContentBlockSchema,
+  MapBlockSchema,
+  MapFullPageBlockSchema,
+  ScrollytellingBlockSchema,
+  MixedBlockSchema
+]);
+var PageSchema = z.object({
+  path: z.string().describe('URL path (e.g., "/", "/about")'),
+  title: z.string().describe("Page title"),
+  description: z.string().optional().describe("Page description for SEO"),
+  blocks: z.array(BlockSchema).describe("Page content blocks")
+}).describe("Page configuration");
+var GlobalConfigSchema = z.object({
+  title: z.string().optional().describe("Application title"),
+  description: z.string().optional().describe("Application description"),
+  defaultMapStyle: z.string().url().optional().describe("Default map style URL"),
+  theme: z.enum(["light", "dark"]).default("light").describe("Default theme"),
+  dataFetching: z.object({
+    defaultStrategy: z.enum(["runtime", "build", "hybrid"]).default("runtime").describe("Default fetch strategy"),
+    timeout: z.number().min(1e3).default(3e4).describe("Default timeout in milliseconds"),
+    retryAttempts: z.number().int().min(0).default(3).describe("Default retry attempts")
+  }).optional().describe("Data fetching configuration")
+}).describe("Global configuration");
+var RootSchema = z.object({
+  config: GlobalConfigSchema.optional().describe("Global configuration"),
+  layers: z.record(LayerSchema).optional().describe("Named layer definitions for reuse"),
+  sources: z.record(LayerSourceSchema).optional().describe("Named source definitions for reuse"),
+  pages: z.array(PageSchema).min(1, "At least one page is required").describe("Page definitions")
+}).describe("Root configuration schema");
+
+// src/parser/yaml-parser.ts
+var YAMLParser = class {
+  /**
+   * Parse YAML string and validate against schema
+   *
+   * @param yaml - YAML string to parse
+   * @returns Validated configuration object
+   * @throws {Error} If YAML syntax is invalid
+   * @throws {ZodError} If validation fails
+   *
+   * @remarks
+   * This method parses the YAML, validates it against the RootSchema,
+   * resolves all references, and returns the validated config. If any
+   * step fails, it throws an error.
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   const config = YAMLParser.parse(yamlString);
+   *   console.log('Valid config:', config);
+   * } catch (error) {
+   *   console.error('Parse error:', error.message);
+   * }
+   * ```
+   */
+  static parse(yaml) {
+    let parsed;
+    try {
+      parsed = parse(yaml);
+    } catch (error) {
+      throw new Error(
+        `YAML syntax error: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    const validated = RootSchema.parse(parsed);
+    return this.resolveReferences(validated);
+  }
+  /**
+   * Parse YAML string and validate, returning a result object
+   *
+   * @param yaml - YAML string to parse
+   * @returns Result object with success flag and either data or errors
+   *
+   * @remarks
+   * This is the non-throwing version of {@link parse}. Instead of throwing
+   * errors, it returns a result object that indicates success or failure.
+   * Use this when you want to handle errors gracefully without try/catch.
+   *
+   * @example
+   * ```typescript
+   * const result = YAMLParser.safeParse(yamlString);
+   * if (result.success) {
+   *   console.log('Config:', result.data);
+   * } else {
+   *   result.errors.forEach(err => {
+   *     console.error(`Error at ${err.path}: ${err.message}`);
+   *   });
+   * }
+   * ```
+   */
+  static safeParse(yaml) {
+    try {
+      const data = this.parse(yaml);
+      return {
+        success: true,
+        data,
+        errors: []
+      };
+    } catch (error) {
+      if (error instanceof ZodError) {
+        return {
+          success: false,
+          errors: this.formatZodErrors(error)
+        };
+      }
+      return {
+        success: false,
+        errors: [
+          {
+            path: "",
+            message: error instanceof Error ? error.message : String(error)
+          }
+        ]
+      };
+    }
+  }
+  /**
+   * Validate a JavaScript object against the schema
+   *
+   * @param config - JavaScript object to validate
+   * @returns Validated configuration object
+   * @throws {ZodError} If validation fails
+   *
+   * @remarks
+   * This method bypasses YAML parsing and directly validates a JavaScript object.
+   * Useful when you already have a parsed object (e.g., from JSON.parse) and just
+   * want to validate and resolve references.
+   *
+   * @example
+   * ```typescript
+   * const jsConfig = JSON.parse(jsonString);
+   * const validated = YAMLParser.validate(jsConfig);
+   * ```
+   */
+  static validate(config) {
+    const validated = RootSchema.parse(config);
+    return this.resolveReferences(validated);
+  }
+  /**
+   * Resolve $ref references to global layers and sources
+   *
+   * @param config - Configuration object with potential references
+   * @returns Configuration with all references resolved
+   * @throws {Error} If a reference cannot be resolved
+   *
+   * @remarks
+   * References use JSON Pointer-like syntax: `#/layers/layerName` or `#/sources/sourceName`.
+   * This method walks the configuration tree, finds all objects with a `$ref` property,
+   * looks up the referenced item in `config.layers` or `config.sources`, and replaces
+   * the reference object with the actual item.
+   *
+   * ## Reference Syntax
+   *
+   * - `#/layers/myLayer` - Reference to a layer in the global `layers` section
+   * - `#/sources/mySource` - Reference to a source in the global `sources` section
+   *
+   * @example
+   * ```typescript
+   * const config = {
+   *   layers: {
+   *     myLayer: { id: 'layer1', type: 'circle', ... }
+   *   },
+   *   pages: [{
+   *     blocks: [{
+   *       type: 'map',
+   *       layers: [{ $ref: '#/layers/myLayer' }]
+   *     }]
+   *   }]
+   * };
+   *
+   * const resolved = YAMLParser.resolveReferences(config);
+   * // resolved.pages[0].blocks[0].layers[0] now contains the full layer object
+   * ```
+   */
+  static resolveReferences(config) {
+    const resolveInObject = (obj) => {
+      if (obj == null) return obj;
+      if (Array.isArray(obj)) {
+        return obj.map((item) => resolveInObject(item));
+      }
+      if (typeof obj === "object") {
+        if ("$ref" in obj && typeof obj.$ref === "string") {
+          const ref = obj.$ref;
+          const match = ref.match(/^#\/(layers|sources)\/(.+)$/);
+          if (!match) {
+            throw new Error(
+              `Invalid reference format: ${ref}. Expected #/layers/name or #/sources/name`
+            );
+          }
+          const [, section, name] = match;
+          if (section === "layers") {
+            if (!config.layers || !(name in config.layers)) {
+              throw new Error(`Layer reference not found: ${ref}`);
+            }
+            return config.layers[name];
+          } else if (section === "sources") {
+            if (!config.sources || !(name in config.sources)) {
+              throw new Error(`Source reference not found: ${ref}`);
+            }
+            return config.sources[name];
+          }
+        }
+        const resolved = {};
+        for (const [key, value] of Object.entries(obj)) {
+          resolved[key] = resolveInObject(value);
+        }
+        return resolved;
+      }
+      return obj;
+    };
+    return resolveInObject(config);
+  }
+  /**
+   * Format Zod validation errors into user-friendly messages
+   *
+   * @param error - Zod validation error
+   * @returns Array of formatted error objects
+   *
+   * @remarks
+   * This method transforms Zod's internal error format into human-readable
+   * messages with clear paths and descriptions. It handles various Zod error
+   * types and provides appropriate messages for each.
+   *
+   * ## Error Type Handling
+   *
+   * - `invalid_type`: Type mismatch (e.g., expected number, got string)
+   * - `invalid_union_discriminator`: Invalid discriminator for union types
+   * - `invalid_union`: None of the union options matched
+   * - `too_small`: Value below minimum (arrays, strings, numbers)
+   * - `too_big`: Value above maximum
+   * - `invalid_string`: String format validation failed
+   * - `custom`: Custom validation refinement failed
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   RootSchema.parse(invalidConfig);
+   * } catch (error) {
+   *   if (error instanceof ZodError) {
+   *     const formatted = YAMLParser.formatZodErrors(error);
+   *     formatted.forEach(err => {
+   *       console.error(`${err.path}: ${err.message}`);
+   *     });
+   *   }
+   * }
+   * ```
+   */
+  static formatZodErrors(error) {
+    return error.errors.map((err) => {
+      const path = err.path.join(".");
+      let message;
+      switch (err.code) {
+        case "invalid_type":
+          message = `Expected ${err.expected}, got ${err.received}`;
+          break;
+        case "invalid_union_discriminator":
+          message = `Invalid type. Expected one of: ${err.options.join(", ")}`;
+          break;
+        case "invalid_union":
+          message = "Value does not match any of the expected formats";
+          break;
+        case "too_small":
+          if (err.type === "array") {
+            message = `Array must have at least ${err.minimum} element(s)`;
+          } else if (err.type === "string") {
+            message = `String must have at least ${err.minimum} character(s)`;
+          } else {
+            message = `Value must be >= ${err.minimum}`;
+          }
+          break;
+        case "too_big":
+          if (err.type === "array") {
+            message = `Array must have at most ${err.maximum} element(s)`;
+          } else if (err.type === "string") {
+            message = `String must have at most ${err.maximum} character(s)`;
+          } else {
+            message = `Value must be <= ${err.maximum}`;
+          }
+          break;
+        case "invalid_string":
+          if (err.validation === "url") {
+            message = "Invalid URL format";
+          } else if (err.validation === "email") {
+            message = "Invalid email format";
+          } else {
+            message = `Invalid string format: ${err.validation}`;
+          }
+          break;
+        case "custom":
+          message = err.message || "Validation failed";
+          break;
+        default:
+          message = err.message || "Validation error";
+      }
+      return {
+        path,
+        message
+      };
+    });
+  }
+};
+YAMLParser.parse.bind(YAMLParser);
+var safeParseYAMLConfig = YAMLParser.safeParse.bind(YAMLParser);
+
+// src/components/ml-map.ts
+var MLMap = class extends HTMLElement {
+  renderer = null;
+  container = null;
+  /**
+   * Observed attributes that trigger attributeChangedCallback
+   */
+  static get observedAttributes() {
+    return ["config"];
+  }
+  /**
+   * Called when element is added to the DOM
+   */
+  connectedCallback() {
+    this.container = document.createElement("div");
+    this.container.style.width = "100%";
+    this.container.style.height = "100%";
+    this.appendChild(this.container);
+    const config = this.getConfig();
+    if (config) {
+      this.render(config);
+    } else {
+      this.dispatchEvent(
+        new CustomEvent("error", {
+          detail: { error: new Error("No valid map configuration found") }
+        })
+      );
+    }
+  }
+  /**
+   * Called when element is removed from the DOM
+   */
+  disconnectedCallback() {
+    if (this.renderer) {
+      this.renderer.destroy();
+      this.renderer = null;
+    }
+    if (this.container) {
+      this.container.remove();
+      this.container = null;
+    }
+  }
+  /**
+   * Called when an observed attribute changes
+   */
+  attributeChangedCallback(name, oldValue, newValue) {
+    if (name === "config" && oldValue !== newValue && this.container) {
+      if (this.renderer) {
+        this.renderer.destroy();
+        this.renderer = null;
+      }
+      const config = this.getConfig();
+      if (config) {
+        this.render(config);
+      }
+    }
+  }
+  /**
+   * Get configuration from one of three sources:
+   * 1. 'config' attribute (JSON string)
+   * 2. Inline <script type="application/yaml">
+   * 3. Inline <script type="application/json">
+   */
+  getConfig() {
+    const configAttr = this.getAttribute("config");
+    if (configAttr) {
+      try {
+        const parsed = JSON.parse(configAttr);
+        const result = MapBlockSchema.safeParse(parsed);
+        if (result.success) {
+          return result.data;
+        } else {
+          console.error("Invalid map config in attribute:", result.error);
+        }
+      } catch (error) {
+        console.error("Failed to parse config attribute as JSON:", error);
+      }
+    }
+    const yamlScript = this.querySelector(
+      'script[type="application/yaml"]'
+    );
+    if (yamlScript?.textContent) {
+      try {
+        const parsed = safeParseYAMLConfig(yamlScript.textContent);
+        if (parsed.success) {
+          for (const page of parsed.data.pages || []) {
+            const mapBlock = page.blocks?.find(
+              (block) => block.type === "map"
+            );
+            if (mapBlock) {
+              return mapBlock;
+            }
+          }
+        } else {
+          console.error("Invalid YAML config:", parsed.errors);
+        }
+      } catch (error) {
+        console.error("Failed to parse YAML config:", error);
+      }
+    }
+    const jsonScript = this.querySelector(
+      'script[type="application/json"]'
+    );
+    if (jsonScript?.textContent) {
+      try {
+        const parsed = JSON.parse(jsonScript.textContent);
+        const result = MapBlockSchema.safeParse(parsed);
+        if (result.success) {
+          return result.data;
+        } else {
+          console.error("Invalid JSON config:", result.error);
+        }
+      } catch (error) {
+        console.error("Failed to parse JSON config:", error);
+      }
+    }
+    return null;
+  }
+  /**
+   * Render the map with the given configuration
+   */
+  render(config) {
+    if (!this.container) return;
+    try {
+      this.renderer = new MapRenderer(
+        this.container,
+        config.config,
+        config.layers || [],
+        {
+          onLoad: () => {
+            if (config.controls) {
+              this.renderer?.addControls(config.controls);
+            }
+            this.dispatchEvent(
+              new CustomEvent("load", {
+                detail: { map: this.renderer?.getMap() }
+              })
+            );
+          },
+          onError: (error) => {
+            this.dispatchEvent(
+              new CustomEvent("error", {
+                detail: { error }
+              })
+            );
+          }
+        }
+      );
+    } catch (error) {
+      this.dispatchEvent(
+        new CustomEvent("error", {
+          detail: { error }
+        })
+      );
+    }
+  }
+  /**
+   * Get the underlying MapRenderer instance
+   */
+  getRenderer() {
+    return this.renderer;
+  }
+  /**
+   * Get the underlying MapLibre Map instance
+   */
+  getMap() {
+    return this.renderer?.getMap() ?? null;
+  }
+};
+if (typeof window !== "undefined" && !customElements.get("ml-map")) {
+  customElements.define("ml-map", MLMap);
+}
+
+// src/components/styles.ts
+var defaultStyles = `
+  ml-map {
+    display: block;
+    position: relative;
+    width: 100%;
+    height: 400px;
+  }
+
+  ml-map > div {
+    width: 100%;
+    height: 100%;
+  }
+
+  ml-map script[type="application/yaml"],
+  ml-map script[type="application/json"] {
+    display: none;
+  }
+`;
+function injectStyles() {
+  if (typeof document === "undefined") return;
+  const existingStyle = document.getElementById("ml-map-styles");
+  if (existingStyle) return;
+  const style = document.createElement("style");
+  style.id = "ml-map-styles";
+  style.textContent = defaultStyles;
+  document.head.appendChild(style);
+}
+if (typeof window !== "undefined") {
+  injectStyles();
+}
+
+export { MLMap, defaultStyles, injectStyles };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map