@maplibre-yaml/core 0.1.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,2717 @@
+import { RootSchema } from './schemas/index.js';
+export { BlockSchema, ChapterActionSchema, ChapterLayersSchema, ChapterSchema, ColorOrExpressionSchema, ColorSchema, ContentBlockSchema, ContentElementSchema, ContentItemSchema, ExpressionSchema, GeoJSONSourceSchema, GlobalConfigSchema, ImageSourceSchema, LatitudeSchema, LayerSourceSchema, LngLatBoundsSchema, LngLatSchema, LoadingConfigSchema, LongitudeSchema, MixedBlockSchema, NumberOrExpressionSchema, PageSchema, RasterSourceSchema, ScrollytellingBlockSchema, StreamConfigSchema, ValidTagNames, VectorSourceSchema, VideoSourceSchema, ZoomLevelSchema } from './schemas/index.js';
+import { L as LayerSchema, P as PopupContentSchema, C as ControlsConfigSchema } from './map.schema-EnZRrtIh.js';
+export { h as BackgroundLayerSchema, B as BaseLayerPropertiesSchema, d as CircleLayerSchema, k as ControlPositionSchema, f as FillExtrusionLayerSchema, F as FillLayerSchema, H as HeatmapLayerSchema, g as HillshadeLayerSchema, I as InteractiveConfigSchema, j as LayerOrReferenceSchema, i as LayerReferenceSchema, a as LegendConfigSchema, c as LegendItemSchema, e as LineLayerSchema, l as MapBlockSchema, M as MapConfigSchema, m as MapFullPageBlockSchema, b as PopupContentItemSchema, R as RasterLayerSchema, S as SymbolLayerSchema } from './map.schema-EnZRrtIh.js';
+import { z } from 'zod';
+export { L as LegendBuilder, M as MapRenderer, b as MapRendererEvents, a as MapRendererOptions } from './map-renderer-RQc5_bdo.js';
+import { Map, LngLat } from 'maplibre-gl';
+import { FeatureCollection } from 'geojson';
+
+/**
+ * @file YAML parser for MapLibre configuration files
+ * @module @maplibre-yaml/core/parser
+ *
+ * @description
+ * This module provides YAML parsing, schema validation, and reference resolution
+ * for MapLibre YAML configuration files. It converts YAML strings into validated
+ * TypeScript objects ready for rendering.
+ *
+ * ## Features
+ *
+ * - **YAML Parsing**: Converts YAML strings to JavaScript objects
+ * - **Schema Validation**: Validates against Zod schemas with detailed error messages
+ * - **Reference Resolution**: Resolves `$ref` pointers to global layers and sources
+ * - **Error Formatting**: Transforms Zod errors into user-friendly messages with paths
+ *
+ * @example
+ * Basic parsing
+ * ```typescript
+ * import { YAMLParser } from '@maplibre-yaml/core/parser';
+ *
+ * const yaml = `
+ * pages:
+ *   - path: "/"
+ *     title: "My Map"
+ *     blocks:
+ *       - type: map
+ *         id: main
+ *         config:
+ *           center: [0, 0]
+ *           zoom: 2
+ *           mapStyle: "https://example.com/style.json"
+ * `;
+ *
+ * const config = YAMLParser.parse(yaml);
+ * ```
+ *
+ * @example
+ * Safe parsing with error handling
+ * ```typescript
+ * const result = YAMLParser.safeParse(yaml);
+ * if (result.success) {
+ *   console.log('Valid config:', result.data);
+ * } else {
+ *   result.errors.forEach(err => {
+ *     console.error(`${err.path}: ${err.message}`);
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * Reference resolution
+ * ```typescript
+ * const yaml = `
+ * layers:
+ *   myLayer:
+ *     id: shared
+ *     type: circle
+ *     source: { type: geojson, data: {...} }
+ *
+ * pages:
+ *   - path: "/"
+ *     blocks:
+ *       - type: map
+ *         layers:
+ *           - $ref: "#/layers/myLayer"
+ * `;
+ *
+ * const config = YAMLParser.parse(yaml);
+ * // References are automatically resolved
+ * ```
+ */
+
+/**
+ * Type alias for the root configuration object
+ *
+ * @remarks
+ * Inferred from the RootSchema Zod schema
+ */
+type RootConfig = z.infer<typeof RootSchema>;
+/**
+ * Error information for a single validation or parsing error
+ *
+ * @property path - JSON path to the error location (e.g., "pages[0].blocks[1].config.center")
+ * @property message - Human-readable error description
+ * @property line - Optional line number in the YAML file where error occurred
+ * @property column - Optional column number in the YAML file where error occurred
+ */
+interface ParseError {
+    path: string;
+    message: string;
+    line?: number;
+    column?: number;
+}
+/**
+ * Result object returned by safeParse operations
+ *
+ * @property success - Whether parsing and validation succeeded
+ * @property data - Validated configuration object (only present if success is true)
+ * @property errors - Array of errors (only present if success is false)
+ */
+interface ParseResult {
+    success: boolean;
+    data?: RootConfig;
+    errors: ParseError[];
+}
+/**
+ * YAML parser with schema validation and reference resolution
+ *
+ * @remarks
+ * This class provides static methods for parsing YAML configuration files,
+ * validating them against schemas, and resolving references between configuration
+ * sections. All methods are static as the parser maintains no internal state.
+ *
+ * @example
+ * Parse and validate YAML (throws on error)
+ * ```typescript
+ * const config = YAMLParser.parse(yamlString);
+ * ```
+ *
+ * @example
+ * Safe parse (returns result object)
+ * ```typescript
+ * const result = YAMLParser.safeParse(yamlString);
+ * if (!result.success) {
+ *   console.error('Validation errors:', result.errors);
+ * }
+ * ```
+ */
+declare class YAMLParser {
+    /**
+     * 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: string): RootConfig;
+    /**
+     * 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: string): ParseResult;
+    /**
+     * 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: unknown): RootConfig;
+    /**
+     * 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: RootConfig): RootConfig;
+    /**
+     * 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}`);
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    private static formatZodErrors;
+}
+/**
+ * Convenience function to parse YAML config
+ *
+ * @param yaml - YAML string to parse
+ * @returns Validated configuration object
+ * @throws {Error} If parsing or validation fails
+ *
+ * @remarks
+ * This is an alias for {@link YAMLParser.parse} for convenient imports.
+ *
+ * @example
+ * ```typescript
+ * import { parseYAMLConfig } from '@maplibre-yaml/core/parser';
+ * const config = parseYAMLConfig(yamlString);
+ * ```
+ */
+declare const parseYAMLConfig: typeof YAMLParser.parse;
+/**
+ * Convenience function to safely parse YAML config
+ *
+ * @param yaml - YAML string to parse
+ * @returns Result object with success flag and data or errors
+ *
+ * @remarks
+ * This is an alias for {@link YAMLParser.safeParse} for convenient imports.
+ *
+ * @example
+ * ```typescript
+ * import { safeParseYAMLConfig } from '@maplibre-yaml/core/parser';
+ * const result = safeParseYAMLConfig(yamlString);
+ * if (result.success) {
+ *   console.log(result.data);
+ * }
+ * ```
+ */
+declare const safeParseYAMLConfig: typeof YAMLParser.safeParse;
+
+/**
+ * @file Layer manager for MapLibre map layers
+ * @module @maplibre-yaml/core/renderer
+ */
+
+type Layer = z.infer<typeof LayerSchema>;
+/**
+ * Callbacks for layer data loading events
+ */
+interface LayerManagerCallbacks {
+    onDataLoading?: (layerId: string) => void;
+    onDataLoaded?: (layerId: string, featureCount: number) => void;
+    onDataError?: (layerId: string, error: Error) => void;
+}
+/**
+ * Manages map layers and their data sources
+ */
+declare class LayerManager {
+    private map;
+    private callbacks;
+    private dataFetcher;
+    private pollingManager;
+    private streamManager;
+    private dataMerger;
+    private loadingManager;
+    private sourceData;
+    private layerToSource;
+    private refreshIntervals;
+    private abortControllers;
+    constructor(map: Map, callbacks?: LayerManagerCallbacks);
+    addLayer(layer: Layer): Promise<void>;
+    private addSource;
+    private addGeoJSONSourceFromURL;
+    /**
+     * Setup polling and/or streaming for a GeoJSON source
+     */
+    private setupDataUpdates;
+    /**
+     * Handle incoming data updates with merge strategy
+     */
+    private handleDataUpdate;
+    /**
+     * Pause data refresh for a layer (polling)
+     */
+    pauseRefresh(layerId: string): void;
+    /**
+     * Resume data refresh for a layer (polling)
+     */
+    resumeRefresh(layerId: string): void;
+    /**
+     * Force immediate refresh for a layer (polling)
+     */
+    refreshNow(layerId: string): Promise<void>;
+    /**
+     * Disconnect streaming connection for a layer
+     */
+    disconnectStream(layerId: string): void;
+    removeLayer(layerId: string): void;
+    setVisibility(layerId: string, visible: boolean): void;
+    updateData(layerId: string, data: GeoJSON.GeoJSON): void;
+    /**
+     * @deprecated Legacy refresh method - use PollingManager instead
+     */
+    startRefreshInterval(layer: Layer): void;
+    stopRefreshInterval(layerId: string): void;
+    clearAllIntervals(): void;
+    destroy(): void;
+}
+
+/**
+ * @file Event handler for map layer interactions
+ * @module @maplibre-yaml/core/renderer
+ */
+
+/**
+ * Callbacks for interactive events
+ */
+interface EventHandlerCallbacks {
+    onClick?: (layerId: string, feature: any, lngLat: LngLat) => void;
+    onHover?: (layerId: string, feature: any, lngLat: LngLat) => void;
+}
+
+/**
+ * @file Popup HTML builder for map features
+ * @module @maplibre-yaml/core/renderer
+ */
+
+type PopupContent = z.infer<typeof PopupContentSchema>;
+/**
+ * Builds popup HTML from configuration and feature properties
+ */
+declare class PopupBuilder {
+    /**
+     * Build HTML string from popup content config and feature properties
+     */
+    build(content: PopupContent, properties: Record<string, any>): string;
+    /**
+     * Build a single content item
+     */
+    private buildItem;
+    /**
+     * Format a number according to format string
+     */
+    private formatNumber;
+    /**
+     * Escape HTML to prevent XSS
+     */
+    private escapeHtml;
+}
+
+/**
+ * @file Controls manager for map controls
+ * @module @maplibre-yaml/core/renderer
+ */
+
+type ControlsConfig = z.infer<typeof ControlsConfigSchema>;
+/**
+ * Manages MapLibre map controls (navigation, geolocate, scale, etc.)
+ */
+declare class ControlsManager {
+    private map;
+    private addedControls;
+    constructor(map: Map);
+    /**
+     * Add controls to the map based on configuration
+     */
+    addControls(config: ControlsConfig): void;
+    /**
+     * Remove all controls from the map
+     */
+    removeAllControls(): void;
+}
+
+/**
+ * @file TTL-based in-memory cache for fetched data
+ * @module @maplibre-yaml/core/data
+ */
+/**
+ * Configuration options for MemoryCache
+ */
+interface CacheConfig {
+    /**
+     * Maximum number of entries to store
+     * @default 100
+     */
+    maxSize: number;
+    /**
+     * Default time-to-live in milliseconds
+     * @default 300000 (5 minutes)
+     */
+    defaultTTL: number;
+    /**
+     * Whether to use conditional requests with ETag/Last-Modified headers
+     * @default true
+     */
+    useConditionalRequests: boolean;
+}
+/**
+ * Cache entry containing data and metadata
+ */
+interface CacheEntry<T = unknown> {
+    /** Cached data */
+    data: T;
+    /** Timestamp when cached (milliseconds) */
+    timestamp: number;
+    /** Time-to-live for this entry in milliseconds (overrides default) */
+    ttl?: number;
+    /** ETag header from HTTP response */
+    etag?: string;
+    /** Last-Modified header from HTTP response */
+    lastModified?: string;
+}
+/**
+ * Cache statistics
+ */
+interface CacheStats {
+    /** Number of entries currently in cache */
+    size: number;
+    /** Total number of cache hits */
+    hits: number;
+    /** Total number of cache misses */
+    misses: number;
+    /** Hit rate as percentage (0-100) */
+    hitRate: number;
+}
+/**
+ * TTL-based in-memory cache with LRU eviction.
+ *
+ * @remarks
+ * Features:
+ * - LRU (Least Recently Used) eviction when at capacity
+ * - Respects HTTP cache headers (ETag, Last-Modified)
+ * - Configurable per-entry TTL
+ * - Support for conditional requests (If-None-Match, If-Modified-Since)
+ * - Automatic expiration checking on get operations
+ *
+ * @example
+ * ```typescript
+ * const cache = new MemoryCache<GeoJSON.FeatureCollection>({
+ *   maxSize: 100,
+ *   defaultTTL: 300000, // 5 minutes
+ * });
+ *
+ * // Store data with ETag
+ * cache.set('https://example.com/data.json', {
+ *   data: geojsonData,
+ *   timestamp: Date.now(),
+ *   etag: '"abc123"',
+ * });
+ *
+ * // Retrieve (returns null if expired or missing)
+ * const entry = cache.get('https://example.com/data.json');
+ * if (entry) {
+ *   console.log('Cache hit:', entry.data);
+ * }
+ *
+ * // Get conditional headers for HTTP request
+ * const headers = cache.getConditionalHeaders('https://example.com/data.json');
+ * // headers = { 'If-None-Match': '"abc123"' }
+ * ```
+ *
+ * @typeParam T - Type of cached data
+ */
+declare class MemoryCache<T = unknown> {
+    private static readonly DEFAULT_CONFIG;
+    private config;
+    private cache;
+    private accessOrder;
+    private stats;
+    /**
+     * Create a new MemoryCache instance
+     *
+     * @param config - Cache configuration options
+     */
+    constructor(config?: Partial<CacheConfig>);
+    /**
+     * 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: string): CacheEntry<T> | null;
+    /**
+     * Check if a key exists in cache (without checking expiration)
+     *
+     * @param key - Cache key
+     * @returns True if key exists in cache
+     */
+    has(key: string): boolean;
+    /**
+     * 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: string, entry: CacheEntry<T>): void;
+    /**
+     * Delete a cache entry
+     *
+     * @param key - Cache key
+     * @returns True if entry was deleted, false if it didn't exist
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all cache entries and reset statistics
+     */
+    clear(): void;
+    /**
+     * 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(): number;
+    /**
+     * Get cache statistics
+     *
+     * @returns Current cache statistics including hit rate
+     */
+    getStats(): CacheStats;
+    /**
+     * 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: string): Record<string, string>;
+    /**
+     * 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: string): void;
+    /**
+     * Update access order for LRU tracking
+     *
+     * @param key - Cache key
+     */
+    private updateAccessOrder;
+    /**
+     * Remove a key from access order array
+     *
+     * @param key - Cache key
+     */
+    private removeFromAccessOrder;
+}
+
+/**
+ * @file HTTP data fetcher with caching and retry support
+ * @module @maplibre-yaml/core/data
+ */
+
+/**
+ * Configuration for DataFetcher
+ */
+interface FetcherConfig {
+    /**
+     * Cache configuration
+     */
+    cache: {
+        /** Whether caching is enabled */
+        enabled: boolean;
+        /** Default TTL in milliseconds */
+        defaultTTL: number;
+        /** Maximum number of cached entries */
+        maxSize: number;
+    };
+    /**
+     * Retry configuration
+     */
+    retry: {
+        /** Whether retry is enabled */
+        enabled: boolean;
+        /** Maximum number of retry attempts */
+        maxRetries: number;
+        /** Initial delay in milliseconds */
+        initialDelay: number;
+        /** Maximum delay in milliseconds */
+        maxDelay: number;
+    };
+    /**
+     * Request timeout in milliseconds
+     * @default 30000
+     */
+    timeout: number;
+    /**
+     * Default headers to include in all requests
+     */
+    defaultHeaders: Record<string, string>;
+}
+/**
+ * Options for individual fetch requests
+ */
+interface FetchOptions {
+    /**
+     * Custom TTL for this request (overrides default)
+     */
+    ttl?: number;
+    /**
+     * Skip cache and force fresh fetch
+     * @default false
+     */
+    skipCache?: boolean;
+    /**
+     * AbortSignal for request cancellation
+     */
+    signal?: AbortSignal;
+    /**
+     * Additional headers for this request
+     */
+    headers?: Record<string, string>;
+    /**
+     * Callback before each retry attempt
+     */
+    onRetry?: (attempt: number, delay: number, error: Error) => void;
+    /**
+     * Callback when fetch starts
+     */
+    onStart?: () => void;
+    /**
+     * Callback when fetch completes successfully
+     */
+    onComplete?: (data: FeatureCollection, fromCache: boolean) => void;
+    /**
+     * Callback when fetch fails
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * Result of a fetch operation
+ */
+interface FetchResult {
+    /** The fetched GeoJSON data */
+    data: FeatureCollection;
+    /** Whether data came from cache */
+    fromCache: boolean;
+    /** Number of features in the collection */
+    featureCount: number;
+    /** Duration of fetch operation in milliseconds */
+    duration: number;
+}
+/**
+ * HTTP data fetcher with caching and retry support.
+ *
+ * @remarks
+ * Features:
+ * - In-memory caching with TTL
+ * - Conditional requests (If-None-Match, If-Modified-Since)
+ * - Automatic retry with exponential backoff
+ * - Request timeout and cancellation
+ * - GeoJSON validation
+ * - Lifecycle callbacks
+ *
+ * @example
+ * ```typescript
+ * const fetcher = new DataFetcher({
+ *   cache: { enabled: true, defaultTTL: 300000, maxSize: 100 },
+ *   retry: { enabled: true, maxRetries: 3, initialDelay: 1000, maxDelay: 10000 },
+ *   timeout: 30000,
+ * });
+ *
+ * // Fetch with caching
+ * const result = await fetcher.fetch('https://example.com/data.geojson');
+ * console.log(`Fetched ${result.featureCount} features in ${result.duration}ms`);
+ *
+ * // Prefetch for later use
+ * await fetcher.prefetch('https://example.com/data2.geojson');
+ *
+ * // Force fresh fetch
+ * const fresh = await fetcher.fetch(url, { skipCache: true });
+ * ```
+ */
+declare class DataFetcher {
+    private static readonly DEFAULT_CONFIG;
+    private config;
+    private cache;
+    private retryManager;
+    private activeRequests;
+    /**
+     * Create a new DataFetcher instance
+     *
+     * @param config - Fetcher configuration
+     */
+    constructor(config?: Partial<FetcherConfig>);
+    /**
+     * 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}`);
+     *     },
+     *   }
+     * );
+     * ```
+     */
+    fetch(url: string, options?: FetchOptions): Promise<FetchResult>;
+    /**
+     * 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);
+     * ```
+     */
+    prefetch(url: string, ttl?: number): Promise<void>;
+    /**
+     * 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: string): void;
+    /**
+     * Clear all cached entries
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics
+     *
+     * @returns Cache stats including size, hits, misses, and hit rate
+     */
+    getCacheStats(): CacheStats;
+    /**
+     * Abort all active requests
+     */
+    abortAll(): void;
+    /**
+     * Fetch with retry logic
+     */
+    private fetchWithRetry;
+    /**
+     * Perform the actual HTTP fetch
+     */
+    private performFetch;
+    /**
+     * Check if an error should trigger a retry
+     */
+    private isRetryableError;
+    /**
+     * Validate that data is a GeoJSON FeatureCollection
+     */
+    private isValidGeoJSON;
+    /**
+     * Merge partial config with defaults
+     */
+    private mergeConfig;
+}
+
+/**
+ * @file Exponential backoff retry manager
+ * @module @maplibre-yaml/core/data
+ */
+/**
+ * Configuration options for retry behavior
+ */
+interface RetryConfig {
+    /**
+     * Maximum number of retry attempts
+     * @default 10
+     */
+    maxRetries: number;
+    /**
+     * Initial delay in milliseconds before first retry
+     * @default 1000
+     */
+    initialDelay: number;
+    /**
+     * Maximum delay in milliseconds between retries
+     * @default 30000
+     */
+    maxDelay: number;
+    /**
+     * Backoff multiplier for exponential backoff
+     * @default 2
+     */
+    backoffFactor: number;
+    /**
+     * Whether to apply random jitter to delays
+     * @default true
+     */
+    jitter: boolean;
+    /**
+     * Jitter factor (percentage of delay to randomize)
+     * @default 0.25
+     */
+    jitterFactor: number;
+}
+/**
+ * Callbacks for retry lifecycle events
+ */
+interface RetryCallbacks {
+    /**
+     * Called before each retry attempt
+     *
+     * @param attempt - Current attempt number (1-indexed)
+     * @param delay - Delay in milliseconds before this retry
+     * @param error - Error that triggered the retry
+     */
+    onRetry?: (attempt: number, delay: number, error: Error) => void;
+    /**
+     * Called when all retry attempts are exhausted
+     *
+     * @param attempts - Total number of attempts made
+     * @param lastError - The final error
+     */
+    onExhausted?: (attempts: number, lastError: Error) => void;
+    /**
+     * Called when operation succeeds
+     *
+     * @param attempts - Number of attempts before success (1 = first try)
+     */
+    onSuccess?: (attempts: number) => void;
+    /**
+     * Predicate to determine if an error is retryable
+     *
+     * @param error - Error to check
+     * @returns True if the error should trigger a retry
+     *
+     * @default All errors are retryable
+     */
+    isRetryable?: (error: Error) => boolean;
+}
+/**
+ * Error thrown when maximum retry attempts are exceeded
+ */
+declare class MaxRetriesExceededError extends Error {
+    lastError: Error;
+    attempts: number;
+    /**
+     * Create a MaxRetriesExceededError
+     *
+     * @param lastError - The error from the final attempt
+     * @param attempts - Number of attempts made
+     */
+    constructor(lastError: Error, attempts: number);
+}
+/**
+ * Retry manager with exponential backoff and jitter.
+ *
+ * @remarks
+ * Implements exponential backoff with the formula:
+ * ```
+ * delay = min(initialDelay * (backoffFactor ^ (attempt - 1)), maxDelay)
+ * ```
+ *
+ * With jitter applied as:
+ * ```
+ * delay = delay + (random(-1, 1) * delay * jitterFactor)
+ * ```
+ *
+ * Jitter helps prevent thundering herd problems when multiple clients
+ * retry simultaneously.
+ *
+ * @example
+ * ```typescript
+ * const retry = new RetryManager({
+ *   maxRetries: 5,
+ *   initialDelay: 1000,
+ *   backoffFactor: 2,
+ * });
+ *
+ * try {
+ *   const result = await retry.execute(
+ *     async () => {
+ *       const response = await fetch('https://api.example.com/data');
+ *       if (!response.ok) throw new Error('Request failed');
+ *       return response.json();
+ *     },
+ *     {
+ *       onRetry: (attempt, delay, error) => {
+ *         console.log(`Retry ${attempt} in ${delay}ms: ${error.message}`);
+ *       },
+ *     }
+ *   );
+ *   console.log('Success:', result);
+ * } catch (error) {
+ *   console.error('All retries failed:', error);
+ * }
+ * ```
+ */
+declare class RetryManager {
+    private static readonly DEFAULT_CONFIG;
+    private config;
+    /**
+     * Create a new RetryManager instance
+     *
+     * @param config - Retry configuration options
+     */
+    constructor(config?: Partial<RetryConfig>);
+    /**
+     * 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;
+     *     },
+     *   }
+     * );
+     * ```
+     */
+    execute<T>(fn: () => Promise<T>, callbacks?: RetryCallbacks): Promise<T>;
+    /**
+     * 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: number): number;
+    /**
+     * Reset internal state
+     *
+     * @remarks
+     * Currently this class is stateless, but this method is provided
+     * for API consistency and future extensibility.
+     */
+    reset(): void;
+    /**
+     * Sleep for specified milliseconds
+     *
+     * @param ms - Milliseconds to sleep
+     * @returns Promise that resolves after the delay
+     */
+    private sleep;
+}
+
+/**
+ * @file Polling manager for periodic data refresh
+ * @module @maplibre-yaml/core/data
+ */
+/**
+ * Configuration for a polling subscription.
+ *
+ * @remarks
+ * The polling manager ensures non-overlapping execution by waiting for each
+ * tick to complete before scheduling the next one. This prevents concurrent
+ * execution of the same polling task.
+ *
+ * @example
+ * ```typescript
+ * const polling = new PollingManager();
+ *
+ * polling.start('vehicles', {
+ *   interval: 5000,
+ *   onTick: async () => {
+ *     const data = await fetch('/api/vehicles');
+ *     updateMap(data);
+ *   },
+ *   onError: (error) => console.error(error),
+ *   immediate: true,
+ *   pauseWhenHidden: true,
+ * });
+ * ```
+ */
+interface PollingConfig {
+    /** Polling interval in milliseconds (minimum 1000ms) */
+    interval: number;
+    /** Function to execute on each tick */
+    onTick: () => Promise<void>;
+    /** Error handler for tick failures */
+    onError?: (error: Error) => void;
+    /** Execute immediately on start (default: false) */
+    immediate?: boolean;
+    /** Pause polling when document is hidden (default: true) */
+    pauseWhenHidden?: boolean;
+}
+/**
+ * Current state of a polling subscription.
+ */
+interface PollingState {
+    /** Whether polling is active */
+    isActive: boolean;
+    /** Whether polling is paused */
+    isPaused: boolean;
+    /** Timestamp of last successful tick */
+    lastTick: number | null;
+    /** Timestamp of next scheduled tick */
+    nextTick: number | null;
+    /** Total number of successful ticks */
+    tickCount: number;
+    /** Total number of errors */
+    errorCount: number;
+}
+/**
+ * Manages polling intervals for data refresh.
+ *
+ * @remarks
+ * Features:
+ * - Independent intervals per subscription
+ * - Visibility-aware (pause when tab hidden)
+ * - Tracks tick count and error count
+ * - Non-overlapping execution (waits for tick to complete)
+ * - Pause/resume functionality
+ * - Manual trigger support
+ *
+ * The polling manager automatically pauses polling when the document becomes
+ * hidden (unless `pauseWhenHidden` is false) and resumes when visible again.
+ *
+ * @example
+ * ```typescript
+ * const polling = new PollingManager();
+ *
+ * // Start polling
+ * polling.start('data-refresh', {
+ *   interval: 10000,
+ *   onTick: async () => {
+ *     await fetchAndUpdateData();
+ *   },
+ *   immediate: true,
+ * });
+ *
+ * // Pause temporarily
+ * polling.pause('data-refresh');
+ *
+ * // Resume
+ * polling.resume('data-refresh');
+ *
+ * // Trigger immediately
+ * await polling.triggerNow('data-refresh');
+ *
+ * // Stop completely
+ * polling.stop('data-refresh');
+ * ```
+ */
+declare class PollingManager {
+    private subscriptions;
+    private visibilityListener;
+    constructor();
+    /**
+     * 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: string, config: PollingConfig): void;
+    /**
+     * Stop a polling subscription and clean up resources.
+     *
+     * @param id - Subscription identifier
+     *
+     * @example
+     * ```typescript
+     * polling.stop('layer-1');
+     * ```
+     */
+    stop(id: string): void;
+    /**
+     * Stop all polling subscriptions.
+     *
+     * @example
+     * ```typescript
+     * polling.stopAll();
+     * ```
+     */
+    stopAll(): void;
+    /**
+     * 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: string): void;
+    /**
+     * Pause all active polling subscriptions.
+     *
+     * @example
+     * ```typescript
+     * polling.pauseAll();
+     * ```
+     */
+    pauseAll(): void;
+    /**
+     * Resume a paused polling subscription.
+     *
+     * @param id - Subscription identifier
+     *
+     * @example
+     * ```typescript
+     * polling.resume('layer-1');
+     * ```
+     */
+    resume(id: string): void;
+    /**
+     * Resume all paused polling subscriptions.
+     *
+     * @example
+     * ```typescript
+     * polling.resumeAll();
+     * ```
+     */
+    resumeAll(): void;
+    /**
+     * 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');
+     * ```
+     */
+    triggerNow(id: string): Promise<void>;
+    /**
+     * 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: string): PollingState | 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(): string[];
+    /**
+     * 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: string): boolean;
+    /**
+     * 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: string, interval: number): void;
+    /**
+     * 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(): void;
+    /**
+     * Execute a single tick for a subscription.
+     */
+    private executeTick;
+    /**
+     * Schedule the next tick for a subscription.
+     */
+    private scheduleNextTick;
+    /**
+     * Setup document visibility listener for automatic pause/resume.
+     */
+    private setupVisibilityListener;
+    /**
+     * Handle document visibility changes.
+     */
+    private handleVisibilityChange;
+    /**
+     * Remove document visibility listener.
+     */
+    private teardownVisibilityListener;
+}
+
+/**
+ * @file Type-safe event emitter utility
+ * @module @maplibre-yaml/core/utils
+ */
+/**
+ * Event handler function type
+ */
+type EventHandler<T> = (data: T) => void;
+/**
+ * Type-safe event emitter with strongly-typed event names and payloads
+ *
+ * @remarks
+ * This class provides a type-safe event emitter pattern where event names
+ * and their payload types are strictly enforced. It's designed to be extended
+ * by classes that need event emission capabilities.
+ *
+ * @example
+ * ```typescript
+ * interface MyEvents {
+ *   connect: void;
+ *   message: { text: string };
+ *   error: { error: Error };
+ * }
+ *
+ * class MyEmitter extends EventEmitter<MyEvents> {
+ *   connect() {
+ *     this.emit('connect', undefined);
+ *   }
+ *
+ *   sendMessage(text: string) {
+ *     this.emit('message', { text });
+ *   }
+ * }
+ *
+ * const emitter = new MyEmitter();
+ * emitter.on('message', (data) => {
+ *   console.log(data.text); // Strongly typed!
+ * });
+ * ```
+ *
+ * @typeParam Events - Record of event names to payload types
+ */
+declare class EventEmitter<Events extends Record<string, unknown>> {
+    private handlers;
+    /**
+     * 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<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>): () => void;
+    /**
+     * 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<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>): void;
+    /**
+     * 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<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>): void;
+    /**
+     * 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 });
+     *   }
+     * }
+     * ```
+     */
+    protected emit<K extends keyof Events>(event: K, data: Events[K]): void;
+    /**
+     * 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<K extends keyof Events>(event?: K): void;
+    /**
+     * 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<K extends keyof Events>(event: K): number;
+    /**
+     * 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(): Array<keyof Events>;
+    /**
+     * 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<K extends keyof Events>(event: K): boolean;
+}
+
+/**
+ * @file Base connection class for streaming connections
+ * @module @maplibre-yaml/core/data/streaming
+ */
+
+/**
+ * Connection state enum.
+ *
+ * @remarks
+ * State transitions:
+ * - disconnected → connecting → connected
+ * - connected → disconnected (on manual disconnect)
+ * - connected → reconnecting → connected (on connection loss with reconnect enabled)
+ * - reconnecting → failed (after max reconnect attempts)
+ */
+type ConnectionState = "disconnected" | "connecting" | "connected" | "reconnecting" | "failed";
+/**
+ * Events emitted by streaming connections.
+ *
+ * @remarks
+ * All connections emit these events to allow consumers to react to
+ * connection lifecycle changes and incoming messages.
+ */
+interface ConnectionEvents extends Record<string, unknown> {
+    /** Emitted when connection is established */
+    connect: void;
+    /** Emitted when connection is closed */
+    disconnect: {
+        reason: string;
+    };
+    /** Emitted when a message is received */
+    message: {
+        data: unknown;
+    };
+    /** Emitted when an error occurs */
+    error: {
+        error: Error;
+    };
+    /** Emitted when attempting to reconnect */
+    reconnecting: {
+        attempt: number;
+        delay: number;
+    };
+    /** Emitted when reconnection succeeds */
+    reconnected: {
+        attempts: number;
+    };
+    /** Emitted when reconnection fails after max attempts */
+    failed: {
+        attempts: number;
+        lastError: Error;
+    };
+    /** Emitted whenever connection state changes */
+    stateChange: {
+        from: ConnectionState;
+        to: ConnectionState;
+    };
+}
+/**
+ * Base configuration for all connection types.
+ */
+interface ConnectionConfig {
+    /** Connection URL */
+    url: string;
+    /** Enable automatic reconnection on disconnect (default: true) */
+    reconnect?: boolean;
+    /** Reconnection retry configuration */
+    reconnectConfig?: Partial<RetryConfig>;
+}
+/**
+ * Abstract base class for streaming connections.
+ *
+ * @remarks
+ * Provides common functionality for all streaming connection types:
+ * - Connection state management
+ * - Event emission via EventEmitter
+ * - Automatic reconnection with exponential backoff
+ * - State change tracking
+ *
+ * Subclasses must implement:
+ * - `connect()`: Establish the connection
+ * - `disconnect()`: Close the connection
+ *
+ * @example
+ * ```typescript
+ * class MyConnection extends BaseConnection {
+ *   async connect(): Promise<void> {
+ *     this.setState('connecting');
+ *     // ... connection logic
+ *     this.setState('connected');
+ *     this.emit('connect', undefined);
+ *   }
+ *
+ *   disconnect(): void {
+ *     // ... disconnection logic
+ *     this.handleDisconnect('Manual disconnect');
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BaseConnection extends EventEmitter<ConnectionEvents> {
+    protected state: ConnectionState;
+    protected config: Required<ConnectionConfig>;
+    protected retryManager: RetryManager;
+    protected reconnectAttempts: number;
+    protected manualDisconnect: boolean;
+    /**
+     * Create a new base connection.
+     *
+     * @param config - Connection configuration
+     */
+    constructor(config: ConnectionConfig);
+    /**
+     * Establish connection to the server.
+     *
+     * @remarks
+     * Must be implemented by subclasses. Should:
+     * 1. Set state to 'connecting'
+     * 2. Establish the connection
+     * 3. Set state to 'connected'
+     * 4. Emit 'connect' event
+     *
+     * @throws Error if connection fails
+     */
+    abstract connect(): Promise<void>;
+    /**
+     * Close the connection.
+     *
+     * @remarks
+     * Must be implemented by subclasses. Should:
+     * 1. Close the underlying connection
+     * 2. Call handleDisconnect() with reason
+     */
+    abstract disconnect(): void;
+    /**
+     * Get current connection state.
+     *
+     * @returns Current state
+     *
+     * @example
+     * ```typescript
+     * const state = connection.getState();
+     * if (state === 'connected') {
+     *   // Connection is ready
+     * }
+     * ```
+     */
+    getState(): ConnectionState;
+    /**
+     * Check if connection is currently connected.
+     *
+     * @returns True if connected
+     *
+     * @example
+     * ```typescript
+     * if (connection.isConnected()) {
+     *   connection.send(data);
+     * }
+     * ```
+     */
+    isConnected(): boolean;
+    /**
+     * Get the number of reconnection attempts.
+     *
+     * @returns Number of reconnect attempts
+     */
+    getReconnectAttempts(): number;
+    /**
+     * 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');
+     * }
+     * ```
+     */
+    protected setState(newState: ConnectionState): void;
+    /**
+     * 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');
+     * };
+     * ```
+     */
+    protected handleDisconnect(reason: string): Promise<void>;
+    /**
+     * Attempt to reconnect with exponential backoff.
+     */
+    private attemptReconnection;
+    /**
+     * 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();
+     * }
+     * ```
+     */
+    protected setManualDisconnect(): void;
+    /**
+     * Reset manual disconnect flag.
+     *
+     * @remarks
+     * Should be called when establishing a new connection to allow
+     * automatic reconnection for subsequent disconnections.
+     */
+    protected resetManualDisconnect(): void;
+}
+
+/**
+ * @file Server-Sent Events connection implementation
+ * @module @maplibre-yaml/core/data/streaming
+ */
+
+/**
+ * Configuration for SSE connections.
+ *
+ * @remarks
+ * Server-Sent Events (SSE) is a server push technology enabling a client
+ * to receive automatic updates from a server via an HTTP connection.
+ *
+ * SSE is unidirectional (server to client only) and automatically handles
+ * reconnection when the connection is lost.
+ */
+interface SSEConfig extends ConnectionConfig {
+    /**
+     * Event types to listen for (default: ['message'])
+     *
+     * @remarks
+     * The EventSource API can listen for custom event types sent by the server.
+     * By default, it listens to the 'message' event type.
+     *
+     * @example
+     * ```typescript
+     * eventTypes: ['update', 'delete', 'create']
+     * ```
+     */
+    eventTypes?: string[];
+    /**
+     * Include credentials in CORS requests (default: false)
+     *
+     * @remarks
+     * When true, the EventSource will include credentials (cookies, authorization
+     * headers, etc.) when making cross-origin requests.
+     */
+    withCredentials?: boolean;
+}
+/**
+ * Server-Sent Events connection.
+ *
+ * @remarks
+ * Primary streaming mechanism for real-time updates. Uses the native
+ * EventSource API for robust, automatic reconnection handling.
+ *
+ * Features:
+ * - Automatic reconnection by the browser
+ * - Event-based message streaming
+ * - JSON message parsing with error handling
+ * - Multiple event type support
+ * - Last event ID tracking for resume
+ *
+ * @example
+ * ```typescript
+ * const sse = new SSEConnection({
+ *   url: 'https://api.example.com/events',
+ *   eventTypes: ['update', 'delete'],
+ * });
+ *
+ * sse.on('message', ({ data }) => {
+ *   console.log('Received:', data);
+ * });
+ *
+ * sse.on('error', ({ error }) => {
+ *   console.error('Error:', error);
+ * });
+ *
+ * await sse.connect();
+ * ```
+ */
+declare class SSEConnection extends BaseConnection {
+    private eventSource;
+    private lastEventId;
+    private readonly 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: SSEConfig);
+    /**
+     * 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');
+     * ```
+     */
+    connect(): Promise<void>;
+    /**
+     * 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(): void;
+    /**
+     * 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(): string | null;
+    /**
+     * Setup event listeners for configured event types.
+     */
+    private setupEventListeners;
+    /**
+     * Handle incoming message event.
+     */
+    private handleMessage;
+    /**
+     * Handle error event from EventSource.
+     */
+    private handleError;
+    /**
+     * Close EventSource and clean up.
+     */
+    private closeEventSource;
+}
+
+/**
+ * @file WebSocket connection implementation
+ * @module @maplibre-yaml/core/data/streaming
+ */
+
+/**
+ * Configuration for WebSocket connections.
+ *
+ * @remarks
+ * WebSocket provides full-duplex communication over a single TCP connection,
+ * enabling bidirectional data flow between client and server.
+ */
+interface WebSocketConfig extends ConnectionConfig {
+    /**
+     * WebSocket sub-protocols to use
+     *
+     * @remarks
+     * Sub-protocols allow the client and server to agree on a specific
+     * protocol on top of WebSocket. Can be a single string or array of strings.
+     *
+     * @example
+     * ```typescript
+     * protocols: 'json'
+     * protocols: ['json', 'msgpack']
+     * ```
+     */
+    protocols?: string | string[];
+}
+/**
+ * WebSocket connection for bidirectional streaming.
+ *
+ * @remarks
+ * Provides real-time bidirectional communication with automatic reconnection.
+ * Unlike SSE, WebSocket supports sending data from client to server.
+ *
+ * Features:
+ * - Full-duplex communication
+ * - JSON message parsing with text fallback
+ * - Manual reconnection with exponential backoff
+ * - Sub-protocol support
+ * - Send capability with connection validation
+ *
+ * @example
+ * ```typescript
+ * const ws = new WebSocketConnection({
+ *   url: 'wss://api.example.com/stream',
+ *   protocols: 'json',
+ * });
+ *
+ * ws.on('message', ({ data }) => {
+ *   console.log('Received:', data);
+ * });
+ *
+ * await ws.connect();
+ * ws.send({ type: 'subscribe', channel: 'updates' });
+ * ```
+ */
+declare class WebSocketConnection extends BaseConnection {
+    private ws;
+    private readonly 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: WebSocketConfig);
+    /**
+     * 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');
+     * ```
+     */
+    connect(): Promise<void>;
+    /**
+     * 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(): void;
+    /**
+     * 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: unknown): void;
+    /**
+     * Setup WebSocket event listeners.
+     */
+    private setupEventListeners;
+    /**
+     * Handle incoming message event.
+     */
+    private handleMessage;
+    /**
+     * Handle close event from WebSocket.
+     */
+    private handleClose;
+    /**
+     * Handle error event from WebSocket.
+     */
+    private handleError;
+    /**
+     * Close WebSocket and clean up.
+     */
+    private closeWebSocket;
+}
+
+/**
+ * Configuration for a streaming connection.
+ *
+ * @example
+ * ```typescript
+ * const config: StreamConfig = {
+ *   type: 'sse',
+ *   url: 'https://api.example.com/events',
+ *   onData: (data) => console.log('Received:', data),
+ *   reconnect: { enabled: true, maxRetries: 10 }
+ * };
+ * ```
+ */
+interface StreamConfig {
+    /** Type of streaming connection */
+    type: "websocket" | "sse";
+    /** URL for the streaming connection */
+    url: string;
+    /** Callback for incoming data */
+    onData: (data: FeatureCollection) => void;
+    /** Callback for connection state changes */
+    onStateChange?: (state: ConnectionState) => void;
+    /** Callback for errors */
+    onError?: (error: Error) => void;
+    /** Reconnection configuration */
+    reconnect?: {
+        enabled?: boolean;
+        maxRetries?: number;
+        initialDelay?: number;
+        maxDelay?: number;
+    };
+    /** Event types to listen for (SSE only) */
+    eventTypes?: string[];
+    /** WebSocket protocols (WebSocket only) */
+    protocols?: string | string[];
+}
+/**
+ * State of a streaming connection.
+ */
+interface StreamState {
+    /** Current connection state */
+    connectionState: ConnectionState;
+    /** Number of messages received */
+    messageCount: number;
+    /** Timestamp of last message (milliseconds) */
+    lastMessage: number | null;
+    /** Number of reconnection attempts */
+    reconnectAttempts: number;
+}
+/**
+ * Manages streaming connections (SSE and WebSocket).
+ *
+ * @remarks
+ * Provides a unified interface for managing multiple streaming connections,
+ * handling connection lifecycle, automatic reconnection, and message routing.
+ *
+ * Features:
+ * - Multiple concurrent connections
+ * - Automatic reconnection with exponential backoff
+ * - Connection state tracking
+ * - Message counting and statistics
+ * - Type-safe callbacks
+ *
+ * @example
+ * ```typescript
+ * const manager = new StreamManager();
+ *
+ * // Connect to SSE stream
+ * await manager.connect('earthquake-feed', {
+ *   type: 'sse',
+ *   url: 'https://earthquake.usgs.gov/events',
+ *   onData: (data) => updateMap(data),
+ *   reconnect: { enabled: true }
+ * });
+ *
+ * // Connect to WebSocket stream
+ * await manager.connect('vehicle-updates', {
+ *   type: 'websocket',
+ *   url: 'wss://transit.example.com/vehicles',
+ *   onData: (data) => updateVehicles(data),
+ *   protocols: ['json']
+ * });
+ *
+ * // Send data via WebSocket
+ * manager.send('vehicle-updates', { type: 'subscribe', channel: 'all' });
+ *
+ * // Check connection state
+ * const state = manager.getState('earthquake-feed');
+ * console.log(`Messages received: ${state?.messageCount}`);
+ *
+ * // Disconnect when done
+ * manager.disconnect('earthquake-feed');
+ * manager.disconnectAll();
+ * ```
+ */
+declare class StreamManager {
+    private subscriptions;
+    /**
+     * 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)
+     * });
+     * ```
+     */
+    connect(id: string, config: StreamConfig): Promise<void>;
+    /**
+     * Disconnect a specific stream.
+     *
+     * @param id - Stream identifier
+     *
+     * @example
+     * ```typescript
+     * manager.disconnect('updates');
+     * ```
+     */
+    disconnect(id: string): void;
+    /**
+     * Disconnect all active streams.
+     *
+     * @example
+     * ```typescript
+     * manager.disconnectAll();
+     * ```
+     */
+    disconnectAll(): void;
+    /**
+     * 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: string): StreamState | 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: string): boolean;
+    /**
+     * Get all active stream IDs.
+     *
+     * @returns Array of active stream identifiers
+     *
+     * @example
+     * ```typescript
+     * const activeStreams = manager.getActiveIds();
+     * console.log(`Active streams: ${activeStreams.join(', ')}`);
+     * ```
+     */
+    getActiveIds(): string[];
+    /**
+     * 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: string, data: unknown): void;
+    /**
+     * Clean up all resources.
+     *
+     * @example
+     * ```typescript
+     * manager.destroy();
+     * ```
+     */
+    destroy(): void;
+    /**
+     * Create a connection instance based on config type.
+     */
+    private createConnection;
+    /**
+     * Setup event handlers for a connection.
+     */
+    private setupEventHandlers;
+    /**
+     * Type guard to check if data is a FeatureCollection.
+     */
+    private isFeatureCollection;
+}
+
+/**
+ * Strategy for merging data.
+ */
+type MergeStrategy = "replace" | "merge" | "append-window";
+/**
+ * Options for merging data.
+ *
+ * @example
+ * ```typescript
+ * // Replace strategy
+ * const replaceOptions: MergeOptions = {
+ *   strategy: 'replace'
+ * };
+ *
+ * // Merge strategy with update key
+ * const mergeOptions: MergeOptions = {
+ *   strategy: 'merge',
+ *   updateKey: 'id'
+ * };
+ *
+ * // Append-window with size and time limits
+ * const windowOptions: MergeOptions = {
+ *   strategy: 'append-window',
+ *   windowSize: 100,
+ *   windowDuration: 3600000,  // 1 hour
+ *   timestampField: 'timestamp'
+ * };
+ * ```
+ */
+interface MergeOptions {
+    /** Merge strategy to use */
+    strategy: MergeStrategy;
+    /** Property key used to identify features for merge strategy */
+    updateKey?: string;
+    /** Maximum number of features to keep (append-window) */
+    windowSize?: number;
+    /** Maximum age of features in milliseconds (append-window) */
+    windowDuration?: number;
+    /** Property field containing timestamp (append-window) */
+    timestampField?: string;
+}
+/**
+ * Result of a merge operation.
+ */
+interface MergeResult {
+    /** Merged feature collection */
+    data: FeatureCollection;
+    /** Number of features added */
+    added: number;
+    /** Number of features updated */
+    updated: number;
+    /** Number of features removed */
+    removed: number;
+    /** Total number of features in result */
+    total: number;
+}
+/**
+ * Merges GeoJSON FeatureCollections using configurable strategies.
+ *
+ * @remarks
+ * Supports three merge strategies:
+ *
+ * **replace**: Complete replacement of existing data
+ * - Replaces all existing features with incoming features
+ * - Simple and efficient for full updates
+ *
+ * **merge**: Update by key, keep unmatched
+ * - Updates existing features by matching on a key property
+ * - Adds new features that don't match existing keys
+ * - Preserves existing features not in the update
+ * - Requires `updateKey` option
+ *
+ * **append-window**: Add with time/size limits
+ * - Appends incoming features to existing features
+ * - Applies size limit (keeps most recent N features)
+ * - Applies time limit (removes features older than duration)
+ * - Requires `timestampField` for time-based filtering
+ *
+ * @example
+ * ```typescript
+ * const merger = new DataMerger();
+ *
+ * // Replace all data
+ * const result = merger.merge(existing, incoming, {
+ *   strategy: 'replace'
+ * });
+ *
+ * // Merge by vehicle ID
+ * const result = merger.merge(existing, incoming, {
+ *   strategy: 'merge',
+ *   updateKey: 'vehicleId'
+ * });
+ *
+ * // Append with 100 feature limit and 1 hour window
+ * const result = merger.merge(existing, incoming, {
+ *   strategy: 'append-window',
+ *   windowSize: 100,
+ *   windowDuration: 3600000,
+ *   timestampField: 'timestamp'
+ * });
+ * ```
+ */
+declare class DataMerger {
+    /**
+     * 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: FeatureCollection, incoming: FeatureCollection, options: MergeOptions): MergeResult;
+    /**
+     * Replace strategy: Complete replacement of existing data.
+     */
+    private mergeReplace;
+    /**
+     * Merge strategy: Update by key, keep unmatched features.
+     */
+    private mergeMerge;
+    /**
+     * Append-window strategy: Add with time/size limits.
+     */
+    private mergeAppendWindow;
+}
+
+/**
+ * Configuration for the loading manager.
+ */
+interface LoadingConfig {
+    /** Whether to show loading UI overlays (default: false) */
+    showUI: boolean;
+    /** Custom messages for loading states */
+    messages?: {
+        loading?: string;
+        error?: string;
+        retry?: string;
+    };
+    /** Spinner style (default: 'circle') */
+    spinnerStyle?: "circle" | "dots";
+    /** Minimum time to display loading UI in milliseconds (default: 300) */
+    minDisplayTime?: number;
+}
+/**
+ * Events emitted by the loading manager.
+ */
+interface LoadingEvents extends Record<string, unknown> {
+    "loading:start": {
+        layerId: string;
+        message?: string;
+    };
+    "loading:progress": {
+        layerId: string;
+        loaded: number;
+        total?: number;
+    };
+    "loading:complete": {
+        layerId: string;
+        duration: number;
+        fromCache: boolean;
+    };
+    "loading:error": {
+        layerId: string;
+        error: Error;
+        retrying: boolean;
+    };
+    "loading:retry": {
+        layerId: string;
+        attempt: number;
+        delay: number;
+    };
+}
+/**
+ * State of a loading operation.
+ */
+interface LoadingState {
+    /** Whether currently loading */
+    isLoading: boolean;
+    /** When loading started (timestamp) */
+    startTime: number | null;
+    /** Custom loading message */
+    message?: string;
+    /** Current error if any */
+    error?: Error;
+    /** Current retry attempt number */
+    retryAttempt?: number;
+}
+/**
+ * Manages loading states and optional UI overlays.
+ *
+ * @remarks
+ * Provides centralized loading state management with optional visual feedback.
+ * Emits events for all loading state changes, allowing external UI integration.
+ * Can optionally show built-in loading overlays with spinners and error messages.
+ *
+ * Features:
+ * - Event-driven state changes
+ * - Optional loading UI overlays
+ * - Customizable messages and spinner styles
+ * - Minimum display time to prevent flashing
+ * - Retry support with visual feedback
+ * - Multiple concurrent loading operations
+ *
+ * @example
+ * ```typescript
+ * const manager = new LoadingManager({
+ *   showUI: true,
+ *   minDisplayTime: 300
+ * });
+ *
+ * // Listen to loading events
+ * manager.on('loading:start', ({ layerId }) => {
+ *   console.log(`Loading ${layerId}...`);
+ * });
+ *
+ * // Show loading state
+ * const container = document.getElementById('map-container');
+ * manager.showLoading('vehicles', container, 'Loading vehicle data...');
+ *
+ * // Hide when complete
+ * manager.hideLoading('vehicles', { fromCache: false });
+ *
+ * // Show error with retry
+ * manager.showError('vehicles', container, new Error('Failed'), () => {
+ *   // Retry logic
+ * });
+ * ```
+ */
+declare class LoadingManager extends EventEmitter<LoadingEvents> {
+    private config;
+    private subscriptions;
+    private static readonly DEFAULT_CONFIG;
+    /**
+     * 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?: Partial<LoadingConfig>);
+    /**
+     * 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: string, container: HTMLElement, message?: string): void;
+    /**
+     * Hide loading state for a layer.
+     *
+     * @param layerId - Layer identifier
+     * @param result - Optional result information
+     *
+     * @example
+     * ```typescript
+     * manager.hideLoading('earthquakes', { fromCache: true });
+     * ```
+     */
+    hideLoading(layerId: string, result?: {
+        fromCache: boolean;
+    }): void;
+    /**
+     * 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: string, container: HTMLElement, error: Error, onRetry?: () => void): void;
+    /**
+     * 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: string, attempt: number, delay: number): void;
+    /**
+     * 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: string): LoadingState | 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: string): boolean;
+    /**
+     * Clear all loading states and UI.
+     *
+     * @example
+     * ```typescript
+     * manager.clearAll();
+     * ```
+     */
+    clearAll(): void;
+    /**
+     * Clean up all resources.
+     *
+     * @example
+     * ```typescript
+     * manager.destroy();
+     * ```
+     */
+    destroy(): void;
+    /**
+     * Create loading overlay element.
+     */
+    private createLoadingOverlay;
+    /**
+     * Create error overlay element.
+     */
+    private createErrorOverlay;
+}
+
+/**
+ * @file Loading UI styles
+ * @module @maplibre-yaml/core/ui/styles
+ */
+/**
+ * CSS styles for loading overlays and spinners.
+ *
+ * @remarks
+ * Includes:
+ * - Loading overlay with backdrop
+ * - Circle spinner animation
+ * - Dots spinner animation
+ * - Error overlay with icon and retry button
+ * - Dark mode support
+ * - Reduced motion support
+ */
+declare const loadingStyles = "\n/* Loading Overlay */\n.mly-loading-overlay {\n  position: absolute;\n  inset: 0;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  background: rgba(255, 255, 255, 0.85);\n  z-index: 1000;\n  backdrop-filter: blur(2px);\n}\n\n.mly-loading-content {\n  display: flex;\n  flex-direction: column;\n  align-items: center;\n  gap: 12px;\n}\n\n.mly-loading-text {\n  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;\n  font-size: 14px;\n  color: #374151;\n  font-weight: 500;\n}\n\n/* Circle Spinner */\n.mly-spinner--circle {\n  width: 40px;\n  height: 40px;\n  border: 3px solid #e5e7eb;\n  border-top-color: #3b82f6;\n  border-radius: 50%;\n  animation: mly-spin 0.8s linear infinite;\n}\n\n@keyframes mly-spin {\n  to {\n    transform: rotate(360deg);\n  }\n}\n\n/* Dots Spinner */\n.mly-spinner--dots {\n  display: flex;\n  gap: 8px;\n}\n\n.mly-spinner--dots::before,\n.mly-spinner--dots::after {\n  content: '';\n  width: 12px;\n  height: 12px;\n  border-radius: 50%;\n  background: #3b82f6;\n  animation: mly-dots 1.4s infinite ease-in-out both;\n}\n\n.mly-spinner--dots::before {\n  animation-delay: -0.32s;\n}\n\n.mly-spinner--dots::after {\n  animation-delay: -0.16s;\n}\n\n@keyframes mly-dots {\n  0%, 80%, 100% {\n    opacity: 0.3;\n    transform: scale(0.8);\n  }\n  40% {\n    opacity: 1;\n    transform: scale(1);\n  }\n}\n\n/* Error Overlay */\n.mly-loading-overlay--error {\n  background: rgba(254, 242, 242, 0.95);\n}\n\n.mly-error-content {\n  display: flex;\n  flex-direction: column;\n  align-items: center;\n  gap: 12px;\n  max-width: 300px;\n  padding: 20px;\n  text-align: center;\n}\n\n.mly-error-icon {\n  font-size: 32px;\n  line-height: 1;\n}\n\n.mly-error-text {\n  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;\n  font-size: 14px;\n  color: #991b1b;\n  font-weight: 500;\n}\n\n.mly-retry-button {\n  padding: 8px 16px;\n  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;\n  font-size: 14px;\n  font-weight: 500;\n  color: white;\n  background: #dc2626;\n  border: none;\n  border-radius: 6px;\n  cursor: pointer;\n  transition: background 0.2s ease;\n}\n\n.mly-retry-button:hover {\n  background: #b91c1c;\n}\n\n.mly-retry-button:active {\n  background: #991b1b;\n}\n\n/* Dark Mode Support */\n@media (prefers-color-scheme: dark) {\n  .mly-loading-overlay {\n    background: rgba(17, 24, 39, 0.85);\n  }\n\n  .mly-loading-text {\n    color: #e5e7eb;\n  }\n\n  .mly-spinner--circle {\n    border-color: #374151;\n    border-top-color: #60a5fa;\n  }\n\n  .mly-spinner--dots::before,\n  .mly-spinner--dots::after {\n    background: #60a5fa;\n  }\n\n  .mly-loading-overlay--error {\n    background: rgba(127, 29, 29, 0.95);\n  }\n\n  .mly-error-text {\n    color: #fecaca;\n  }\n}\n\n/* Reduced Motion Support */\n@media (prefers-reduced-motion: reduce) {\n  .mly-spinner--circle {\n    animation: none;\n    border-top-color: #3b82f6;\n    opacity: 0.7;\n  }\n\n  .mly-spinner--dots::before,\n  .mly-spinner--dots::after {\n    animation: none;\n    opacity: 0.7;\n  }\n\n  .mly-retry-button {\n    transition: none;\n  }\n}\n";
+/**
+ * Inject loading styles into the document.
+ *
+ * @remarks
+ * Automatically called when the loading manager is first used.
+ * Only injects styles once, even if called multiple times.
+ *
+ * @example
+ * ```typescript
+ * import { injectLoadingStyles } from '@maplibre-yaml/core/ui/styles';
+ *
+ * // Manually inject styles
+ * injectLoadingStyles();
+ * ```
+ */
+declare function injectLoadingStyles(): void;
+
+export { BaseConnection, type CacheConfig, type CacheEntry, type CacheStats, type ConnectionConfig, type ConnectionEvents, type ConnectionState, ControlsConfigSchema, ControlsManager, DataFetcher, DataMerger, EventEmitter, type EventHandler, type EventHandlerCallbacks, type FetchOptions, type FetchResult, type FetcherConfig, LayerManager, type LayerManagerCallbacks, LayerSchema, type LoadingConfig, type LoadingEvents, LoadingManager, type LoadingState, MaxRetriesExceededError, MemoryCache, type MergeOptions, type MergeResult, type MergeStrategy, type ParseError, type ParseResult, type PollingConfig, PollingManager, type PollingState, PopupBuilder, PopupContentSchema, type RetryCallbacks, type RetryConfig, RetryManager, type RootConfig, RootSchema, type SSEConfig, SSEConnection, type StreamConfig, StreamManager, type StreamState, type WebSocketConfig, WebSocketConnection, YAMLParser, injectLoadingStyles, loadingStyles, parseYAMLConfig, safeParseYAMLConfig };