@classic-homes/theme-mcp 0.1.20 → 0.1.22

package/dist/cli.js

@@ -17365,6 +17365,2017 @@ interface SankeyData {
   }));
 }
 
+// src/data/maps-catalog.json
+var maps_catalog_default = {
+  version: "0.4.0",
+  packageName: "@classic-homes/maps-core",
+  description: "Core utilities, types, and themes for Classic Theme MapLibre GL components",
+  subpackages: {
+    main: {
+      importPath: "@classic-homes/maps-core",
+      description: "Main entry point with all exports (themes, types, utilities)",
+      modules: {
+        theme: {
+          description: "MapLibre GL theme generation from design tokens",
+          functions: [
+            {
+              name: "generateLightTheme",
+              signature: "() => MapTheme",
+              description: "Generate light theme configuration from design tokens"
+            },
+            {
+              name: "generateDarkTheme",
+              signature: "() => MapTheme",
+              description: "Generate dark theme configuration from design tokens"
+            },
+            {
+              name: "lightTheme",
+              signature: "MapTheme",
+              description: "Pre-generated light theme object (singleton)"
+            },
+            {
+              name: "darkTheme",
+              signature: "MapTheme",
+              description: "Pre-generated dark theme object (singleton)"
+            },
+            {
+              name: "lightBasicStyle",
+              signature: "StyleSpecification",
+              description: "Pre-generated light MapLibre style using OSM raster tiles"
+            },
+            {
+              name: "darkBasicStyle",
+              signature: "StyleSpecification",
+              description: "Pre-generated dark MapLibre style using OSM raster tiles"
+            },
+            {
+              name: "THEME_LIGHT",
+              signature: "'classic-light'",
+              description: "Theme name constant for light theme"
+            },
+            {
+              name: "THEME_DARK",
+              signature: "'classic-dark'",
+              description: "Theme name constant for dark theme"
+            },
+            {
+              name: "generateLightColors",
+              signature: "() => MapThemeColors",
+              description: "Generate light theme colors from design tokens"
+            },
+            {
+              name: "generateDarkColors",
+              signature: "() => MapThemeColors",
+              description: "Generate dark theme colors from design tokens"
+            },
+            {
+              name: "generateLightDataColors",
+              signature: "() => MapDataColors",
+              description: "Generate light theme data visualization colors"
+            },
+            {
+              name: "generateDarkDataColors",
+              signature: "() => MapDataColors",
+              description: "Generate dark theme data visualization colors"
+            },
+            {
+              name: "getTypography",
+              signature: "() => { fontFamily: string; sizes: Record<string, number> }",
+              description: "Get typography settings from design tokens"
+            },
+            {
+              name: "getTheme",
+              signature: "(mode: 'light' | 'dark') => MapTheme",
+              description: "Get a theme by mode name"
+            },
+            {
+              name: "generateBasicStyle",
+              signature: "(theme: MapTheme) => StyleSpecification",
+              description: "Generate a basic OSM raster tile style for a theme"
+            },
+            {
+              name: "generateVectorStyle",
+              signature: "(theme: MapTheme, options?: { tileUrl?: string }) => StyleSpecification",
+              description: "Generate a vector tile style for a theme"
+            },
+            {
+              name: "getBasicStyle",
+              signature: "(mode: 'light' | 'dark') => StyleSpecification",
+              description: "Get a basic raster style by mode name"
+            }
+          ]
+        },
+        format: {
+          description: "Formatting utilities for map coordinates and measurements",
+          functions: [
+            {
+              name: "formatCoordinates",
+              signature: "(coordinates: LngLat, precision?: number, format?: 'decimal' | 'dms' | 'dd') => string",
+              description: "Format coordinates for display (decimal, DMS, or DD format)",
+              example: "formatCoordinates([-122.4194, 37.7749]) // '-122.419400, 37.774900'"
+            },
+            {
+              name: "decimalToDMS",
+              signature: "(decimal: number, type: 'lat' | 'lng') => string",
+              description: "Convert decimal degrees to DMS (degrees, minutes, seconds) format",
+              example: `decimalToDMS(37.7749, 'lat') // '37\xB0 46' 29.6" N'`
+            },
+            {
+              name: "formatDistance",
+              signature: "(meters: number, unit?: 'metric' | 'imperial') => string",
+              description: "Format distance in meters/kilometers or feet/miles",
+              example: "formatDistance(1500) // '1.5 km'"
+            },
+            {
+              name: "formatArea",
+              signature: "(sqMeters: number, unit?: 'metric' | 'imperial') => string",
+              description: "Format area in square meters/kilometers or acres",
+              example: "formatArea(10000) // '1.00 ha'"
+            },
+            {
+              name: "formatBounds",
+              signature: "(bounds: MapBounds | BoundsArray) => string",
+              description: "Format map bounds as readable string"
+            },
+            {
+              name: "formatZoom",
+              signature: "(zoom: number) => string",
+              description: "Format zoom level for display",
+              example: "formatZoom(12.5) // 'Zoom: 12.5'"
+            },
+            {
+              name: "formatBearing",
+              signature: "(bearing: number) => string",
+              description: "Format bearing/rotation as degrees with cardinal direction",
+              example: "formatBearing(45) // '45\xB0 NE'"
+            },
+            {
+              name: "formatPitch",
+              signature: "(pitch: number) => string",
+              description: "Format pitch/tilt for display",
+              example: "formatPitch(60) // '60\xB0 tilt'"
+            },
+            {
+              name: "formatScale",
+              signature: "(scale: number) => string",
+              description: "Format a scale ratio for display",
+              example: "formatScale(50000) // '1:50K'"
+            },
+            {
+              name: "zoomToScale",
+              signature: "(zoom: number, latitude?: number) => number",
+              description: "Approximate the scale ratio from zoom level (varies by latitude)"
+            },
+            {
+              name: "formatPropertyValue",
+              signature: "(value: unknown) => string",
+              description: "Format a property value for display in popups (handles numbers, booleans, arrays)"
+            },
+            {
+              name: "formatFeatureProperties",
+              signature: "(properties: Record<string, unknown>, options?: { exclude?: string[]; include?: string[]; labelMap?: Record<string, string> }) => string",
+              description: "Create a popup content string from feature properties with optional filtering and label mapping"
+            },
+            {
+              name: "formatLabel",
+              signature: "(key: string) => string",
+              description: "Format a property key as a human-readable label (handles snake_case and camelCase)"
+            }
+          ]
+        },
+        accessibility: {
+          description: "Accessibility utilities for screen readers",
+          functions: [
+            {
+              name: "KEYBOARD_CONTROLS",
+              signature: "Record<string, Record<string, string>>",
+              description: "Keyboard shortcut documentation object for map interactions (pan, zoom, rotate, pitch, reset)"
+            },
+            {
+              name: "generateKeyboardControlsDescription",
+              signature: "() => string",
+              description: "Generate a text description of keyboard controls for screen readers"
+            },
+            {
+              name: "generateMapDescription",
+              signature: "(title: string, options?: { center?: LngLat; zoom?: number; featureCount?: number; markerCount?: number; layerTypes?: string[] }) => string",
+              description: "Generate accessible description for a map"
+            },
+            {
+              name: "generateFeatureCollectionDescription",
+              signature: "(title: string, data: GeoJSONFeatureCollection) => string",
+              description: "Generate accessible description for GeoJSON features (counts and geometry types)"
+            },
+            {
+              name: "generateMarkersDescription",
+              signature: "(title: string, markers: MarkerData[]) => string",
+              description: "Generate accessible description for markers (count and first few labels)"
+            },
+            {
+              name: "generateFeatureTable",
+              signature: "(features: GeoJSONFeatureCollection, propertyKeys: string[]) => string",
+              description: "Generate a hidden data table (HTML) for screen readers with sr-only class"
+            },
+            {
+              name: "generateMarkerList",
+              signature: "(markers: MarkerData[]) => string",
+              description: "Generate a hidden marker list (HTML) for screen readers with sr-only class"
+            },
+            {
+              name: "generateMoveAnnouncement",
+              signature: "(center: LngLat, zoom: number, action: 'pan' | 'zoom' | 'move') => string",
+              description: "Generate live region announcement for map navigation changes"
+            }
+          ]
+        },
+        styles: {
+          description: "Styling utilities for map layers",
+          functions: [
+            {
+              name: "createFillStyle",
+              signature: "(options: { color: ColorExpression; opacity?: NumberExpression; outlineColor?: ColorExpression }) => { paint: Record<string, unknown> }",
+              description: "Create a solid polygon/fill style object for MapLibre layers"
+            },
+            {
+              name: "createLineStyle",
+              signature: "(options: { color: ColorExpression; width: NumberExpression; opacity?: NumberExpression; dashArray?: number[]; cap?: 'butt' | 'round' | 'square'; join?: 'bevel' | 'round' | 'miter' }) => { paint: Record<string, unknown>; layout: Record<string, unknown> }",
+              description: "Create a line style object with paint and layout properties"
+            },
+            {
+              name: "createCircleStyle",
+              signature: "(options: { radius: NumberExpression; color: ColorExpression; opacity?: NumberExpression; strokeWidth?: NumberExpression; strokeColor?: ColorExpression; blur?: number }) => { paint: Record<string, unknown> }",
+              description: "Create a circle/point style object for MapLibre layers"
+            },
+            {
+              name: "createExtrusionStyle",
+              signature: "(options: { height: NumberExpression; baseHeight?: NumberExpression; color: ColorExpression; opacity?: number; verticalGradient?: boolean }) => { paint: Record<string, unknown> }",
+              description: "Create a 3D extrusion style object for building layers"
+            },
+            {
+              name: "createHeatmapStyle",
+              signature: "(options: { weight?: NumberExpression; intensity?: NumberExpression; radius?: NumberExpression; opacity?: NumberExpression; colorRamp?: string[] }) => { paint: Record<string, unknown> }",
+              description: "Create a heatmap style object with optional color ramp"
+            },
+            {
+              name: "createHoverExpression",
+              signature: "(baseValue: unknown, hoverValue: unknown, featureStateName?: string) => unknown[]",
+              description: "Create MapLibre expression for hover state colors using feature-state"
+            },
+            {
+              name: "createSelectionExpression",
+              signature: "(baseValue: unknown, selectedValue: unknown, featureStateName?: string) => unknown[]",
+              description: "Create MapLibre expression for selection state colors using feature-state"
+            },
+            {
+              name: "createInteractiveExpression",
+              signature: "(baseValue: unknown, hoverValue: unknown, selectedValue: unknown) => unknown[]",
+              description: "Create combined hover and selection expression (selection takes priority)"
+            },
+            {
+              name: "createCategoricalColorExpression",
+              signature: "(property: string, colorMap: Record<string, string>, defaultColor: string) => unknown[]",
+              description: "Create data-driven color expression based on a property value (match expression)"
+            },
+            {
+              name: "createContinuousColorExpression",
+              signature: "(property: string, stops: [number, string][], interpolation?: 'linear' | 'exponential' | ['cubic-bezier', number, number, number, number]) => unknown[]",
+              description: "Create continuous color ramp expression for numeric properties"
+            },
+            {
+              name: "createZoomExpression",
+              signature: "(stops: [number, number][]) => unknown[]",
+              description: "Create zoom-based interpolation expression for size/width values"
+            },
+            {
+              name: "getHighlightStyle",
+              signature: "(theme?: MapTheme) => { fill: Record<string, unknown>; line: Record<string, unknown>; circle: Record<string, unknown> }",
+              description: "Get pre-configured highlight style properties for hover states"
+            },
+            {
+              name: "getSelectionStyle",
+              signature: "(theme?: MapTheme) => { fill: Record<string, unknown>; line: Record<string, unknown>; circle: Record<string, unknown> }",
+              description: "Get pre-configured selection style properties with hover and selection states"
+            }
+          ]
+        },
+        bounds: {
+          description: "Bounds calculation utilities for GeoJSON data",
+          functions: [
+            {
+              name: "calculateBounds",
+              signature: "(geojson: GeoJSONFeatureCollection | GeoJSONFeature) => BoundsArray | null",
+              description: "Calculate bounds from GeoJSON data, returns [[sw_lng, sw_lat], [ne_lng, ne_lat]] or null"
+            },
+            {
+              name: "extendBounds",
+              signature: "(bounds: BoundsArray, point: LngLat) => BoundsArray",
+              description: "Extend existing bounds to include a new point"
+            },
+            {
+              name: "combineBounds",
+              signature: "(bounds1: BoundsArray, bounds2: BoundsArray) => BoundsArray",
+              description: "Combine two bounds into one that encompasses both"
+            },
+            {
+              name: "isValidBounds",
+              signature: "(bounds: BoundsArray) => boolean",
+              description: "Validate that bounds are properly formed and within valid ranges"
+            }
+          ]
+        },
+        data: {
+          description: "Data loading and validation utilities for GeoJSON",
+          functions: [
+            {
+              name: "loadGeoJSON",
+              signature: "(url: string, options?: LoadGeoJSONOptions) => Promise<LoadGeoJSONResult<T>>",
+              description: "Load GeoJSON data from a URL with timeout support and optional validation"
+            },
+            {
+              name: "validateGeoJSON",
+              signature: "(data: unknown) => ValidationResult",
+              description: "Validate GeoJSON structure, returns { valid, errors, featureCount, geometryTypes }"
+            },
+            {
+              name: "calculateCentroid",
+              signature: "(geojson: GeoJSONFeatureCollection | GeoJSONFeature) => [number, number] | null",
+              description: "Calculate the centroid of GeoJSON data as [lng, lat]"
+            },
+            {
+              name: "countFeaturesByType",
+              signature: "(geojson: GeoJSONFeatureCollection) => Record<string, number>",
+              description: "Count features by geometry type (Point, Polygon, etc.)"
+            },
+            {
+              name: "filterByGeometryType",
+              signature: "(geojson: GeoJSONFeatureCollection, types: string[]) => GeoJSONFeatureCollection",
+              description: "Filter features by geometry type, returns new FeatureCollection"
+            }
+          ]
+        },
+        positioning: {
+          description: "Positioning utilities for map controls",
+          functions: [
+            {
+              name: "BASE_OFFSET",
+              signature: "8",
+              description: "Base offset from map edge in pixels (matches Tailwind's -2)"
+            },
+            {
+              name: "POSITION_CLASSES",
+              signature: "Record<ControlPosition, string>",
+              description: "Tailwind classes for each corner position (top-left, top-right, bottom-left, bottom-right)"
+            },
+            {
+              name: "OFFSET_CLASSES",
+              signature: "Record<ControlPosition, string>",
+              description: "Horizontal offset classes when MapLibre controls are present at the same position"
+            },
+            {
+              name: "computePositionClasses",
+              signature: "(position: ControlPosition, hasControlsAtPosition: boolean) => string",
+              description: "Compute position classes for a control, with optional offset for MapLibre controls"
+            },
+            {
+              name: "computeVerticalOffsetStyle",
+              signature: "(position: ControlPosition, customControlOffset: number, baseOffset?: number) => Record<string, string>",
+              description: "Compute vertical offset style for stacking multiple custom controls"
+            }
+          ]
+        },
+        cluster: {
+          description: "Cluster utilities for MapLibre GL clustering",
+          functions: [
+            {
+              name: "isClusterFeature",
+              signature: "(feature: { properties?: Record<string, unknown> | null }) => boolean",
+              description: "Type guard to check if a feature is a cluster (has cluster_id and point_count)"
+            },
+            {
+              name: "getClusterExpansionZoom",
+              signature: "(map: Map, sourceId: string, clusterId: number) => Promise<number>",
+              description: "Get the zoom level needed to expand a cluster"
+            },
+            {
+              name: "getClusterChildren",
+              signature: "(map: Map, sourceId: string, clusterId: number) => Promise<GeoJSONFeature[]>",
+              description: "Get the immediate children features of a cluster"
+            },
+            {
+              name: "getClusterLeaves",
+              signature: "(map: Map, sourceId: string, clusterId: number, limit?: number, offset?: number) => Promise<GeoJSONFeature[]>",
+              description: "Get all leaf features (individual points) of a cluster"
+            },
+            {
+              name: "expandCluster",
+              signature: "(map: Map, sourceId: string, clusterId: number, center: LngLat, options?: ClusterExpandOptions) => Promise<void>",
+              description: "Expand a cluster by zooming in to show its contents (main utility for click-to-expand)"
+            },
+            {
+              name: "getClusterBounds",
+              signature: "(map: Map, sourceId: string, clusterId: number, limit?: number) => Promise<BoundsArray>",
+              description: "Calculate bounds that encompass all leaves of a cluster"
+            },
+            {
+              name: "expandClusterToBounds",
+              signature: "(map: Map, sourceId: string, clusterId: number, options?: ClusterExpandOptions) => Promise<void>",
+              description: "Expand a cluster by fitting to the bounds of its leaves (alternative to expandCluster)"
+            }
+          ]
+        },
+        lotStyles: {
+          description: "Specialized style utilities for polygon lot visualizations",
+          functions: [
+            {
+              name: "createLotFillStyle",
+              signature: "(options: LotFillStyleOptions) => { paint: Record<string, unknown> }",
+              description: "Create fill style for lot polygons with status-based coloring and hover/selection states"
+            },
+            {
+              name: "createLotOutlineStyle",
+              signature: "(options: LotOutlineStyleOptions) => { paint: Record<string, unknown>; layout: Record<string, unknown> }",
+              description: "Create outline style for lot polygons with zoom-based width scaling"
+            },
+            {
+              name: "createExtrusionHeightExpression",
+              signature: "(options: ExtrusionHeightOptions) => unknown[]",
+              description: "Create MapLibre expression for 3D lot extrusion heights based on property values"
+            },
+            {
+              name: "createStatusColorExpression",
+              signature: "(property: string, colorMap: Record<string, string>, defaultColor: string) => unknown[]",
+              description: "Create data-driven color expression based on lot status property"
+            },
+            {
+              name: "createInteractiveStatusColorExpression",
+              signature: "(property: string, colorMap: Record<string, string>, hoverColor: string, selectedColor: string, defaultColor: string) => unknown[]",
+              description: "Create combined status color expression with hover and selection states using feature-state"
+            }
+          ]
+        },
+        lod: {
+          description: "Level-of-Detail utilities for performance optimization with large datasets",
+          functions: [
+            {
+              name: "groupFeaturesByProperty",
+              signature: "(data: GeoJSONFeatureCollection, options: GroupFeaturesOptions) => FeatureGroup[]",
+              description: "Group features by a property value for LOD aggregation"
+            },
+            {
+              name: "generateConvexHull",
+              signature: "(features: GeoJSONFeature[]) => GeoJSONFeature | null",
+              description: "Generate a convex hull polygon from a set of features"
+            },
+            {
+              name: "generateBoundingPolygon",
+              signature: "(features: GeoJSONFeature[]) => GeoJSONFeature | null",
+              description: "Generate a bounding box polygon from a set of features"
+            },
+            {
+              name: "boundsToPolygon",
+              signature: "(bounds: BoundsArray) => GeoJSONFeature",
+              description: "Convert bounds array to a polygon feature"
+            },
+            {
+              name: "generateLODData",
+              signature: "(data: GeoJSONFeatureCollection, options: GenerateLODOptions) => LODData",
+              description: "Generate multi-level LOD data with aggregated representations at different zoom levels"
+            },
+            {
+              name: "calculateZoomThresholds",
+              signature: "(featureCount: number, minZoom?: number, maxZoom?: number) => number[]",
+              description: "Calculate optimal zoom thresholds based on feature count"
+            },
+            {
+              name: "simplifyPolygon",
+              signature: "(coordinates: number[][][], tolerance: number) => number[][][]",
+              description: "Simplify polygon coordinates using Douglas-Peucker algorithm"
+            },
+            {
+              name: "simplifyFeature",
+              signature: "(feature: GeoJSONFeature, tolerance: number) => GeoJSONFeature",
+              description: "Simplify a single feature's geometry"
+            },
+            {
+              name: "simplifyFeatureCollection",
+              signature: "(data: GeoJSONFeatureCollection, tolerance: number) => GeoJSONFeatureCollection",
+              description: "Simplify all features in a collection"
+            },
+            {
+              name: "simplifyFeatureCollectionWithStats",
+              signature: "(data: GeoJSONFeatureCollection, tolerance: number) => { data: GeoJSONFeatureCollection; stats: SimplificationStats }",
+              description: "Simplify collection and return statistics (point reduction, time)"
+            },
+            {
+              name: "generateLODDataWithSimplification",
+              signature: "(data: GeoJSONFeatureCollection, options: GenerateLODOptions & { simplificationThresholds?: SimplificationThreshold[] }) => LODDataWithSimplification",
+              description: "Generate LOD data with automatic polygon simplification at each level"
+            },
+            {
+              name: "getSimplifiedFeaturesForZoom",
+              signature: "(lodData: LODDataWithSimplification, zoom: number) => GeoJSONFeatureCollection",
+              description: "Get the appropriate simplified features for a given zoom level"
+            },
+            {
+              name: "createDynamicLODManager",
+              signature: "(data: GeoJSONFeatureCollection, options?: DynamicLODOptions) => DynamicLODState",
+              description: "Create a manager for dynamic LOD switching based on zoom and performance"
+            },
+            {
+              name: "getSimplificationToleranceForZoom",
+              signature: "(zoom: number, thresholds?: SimplificationThreshold[]) => number",
+              description: "Get appropriate simplification tolerance for a zoom level"
+            },
+            {
+              name: "DEFAULT_SIMPLIFICATION_THRESHOLDS",
+              signature: "SimplificationThreshold[]",
+              description: "Default zoom-based simplification thresholds"
+            }
+          ]
+        },
+        spatial: {
+          description: "Spatial indexing utilities for efficient viewport queries on large datasets",
+          functions: [
+            {
+              name: "buildSpatialIndex",
+              signature: "(data: GeoJSONFeatureCollection, options?: BuildSpatialIndexOptions) => SpatialIndex",
+              description: "Build a grid-based spatial index for fast viewport queries"
+            },
+            {
+              name: "queryByBounds",
+              signature: "(index: SpatialIndex, bounds: BoundsArray, options?: QuerySpatialIndexOptions) => GeoJSONFeatureCollection",
+              description: "Query features within bounds from a spatial index"
+            },
+            {
+              name: "queryByBoundsWithStats",
+              signature: "(index: SpatialIndex, bounds: BoundsArray, options?: QuerySpatialIndexOptions) => { data: GeoJSONFeatureCollection; stats: QueryStats }",
+              description: "Query features with performance statistics (cells checked, culled percentage)"
+            },
+            {
+              name: "createViewportQuery",
+              signature: "(index: SpatialIndex) => (bounds: BoundsArray) => GeoJSONFeatureCollection",
+              description: "Create a reusable viewport query function"
+            },
+            {
+              name: "createViewportManager",
+              signature: "(data: GeoJSONFeatureCollection, options?: ViewportManagedDataOptions) => ViewportManagedResult",
+              description: "Create a managed viewport system that automatically updates on map move"
+            },
+            {
+              name: "buildRTreeIndex",
+              signature: "(data: GeoJSONFeatureCollection, options?: BuildRTreeIndexOptions) => RTreeIndex",
+              description: "Build an R-tree spatial index (better for clustered/overlapping data)"
+            },
+            {
+              name: "queryRTreeByBounds",
+              signature: "(index: RTreeIndex, bounds: BoundsArray, options?: QuerySpatialIndexOptions) => GeoJSONFeatureCollection",
+              description: "Query features within bounds from an R-tree index"
+            },
+            {
+              name: "queryRTreeByBoundsWithStats",
+              signature: "(index: RTreeIndex, bounds: BoundsArray, options?: QuerySpatialIndexOptions) => { data: GeoJSONFeatureCollection; stats: RTreeQueryStats }",
+              description: "Query R-tree with performance statistics"
+            },
+            {
+              name: "createRTreeViewportManager",
+              signature: "(data: GeoJSONFeatureCollection, options?: ViewportManagedDataOptions) => ViewportManagedResult",
+              description: "Create a managed viewport system using R-tree index"
+            },
+            {
+              name: "createPredictiveViewportManager",
+              signature: "(data: GeoJSONFeatureCollection, options?: ViewportManagedDataOptions) => PredictiveViewportResult",
+              description: "Create viewport manager with predictive pan loading to eliminate pop-in"
+            },
+            {
+              name: "createIdleViewportManager",
+              signature: "(data: GeoJSONFeatureCollection, options?: IdleViewportManagerOptions) => IdleViewportResult",
+              description: "Create viewport manager that defers updates to idle time for smooth panning"
+            }
+          ]
+        },
+        fingerprint: {
+          description: "Fast O(1) GeoJSON equality checking via fingerprinting",
+          functions: [
+            {
+              name: "createGeoJSONFingerprint",
+              signature: "(data: GeoJSONFeatureCollection | GeoJSON.GeoJSON | string | null | undefined) => GeoJSONFingerprint",
+              description: "Create a lightweight fingerprint for fast equality comparison without deep comparison"
+            },
+            {
+              name: "fingerprintEqual",
+              signature: "(a: GeoJSONFingerprint | null, b: GeoJSONFingerprint | null) => boolean",
+              description: "Compare two fingerprints for equality"
+            },
+            {
+              name: "geoJSONEqual",
+              signature: "(a: GeoJSONFeatureCollection | null | undefined, b: GeoJSONFeatureCollection | null | undefined) => boolean",
+              description: "Check if two GeoJSON collections are equal using fingerprinting"
+            }
+          ]
+        },
+        equality: {
+          description: "Deep equality and delta detection utilities for efficient updates",
+          functions: [
+            {
+              name: "deepEqual",
+              signature: "(a: unknown, b: unknown) => boolean",
+              description: "Deep equality comparison optimized for MapLibre expressions and style objects"
+            },
+            {
+              name: "paintPropsEqual",
+              signature: "(a: PaintProps | undefined, b: PaintProps | undefined) => boolean",
+              description: "Check if two paint property objects are equal"
+            },
+            {
+              name: "getChangedPaintProps",
+              signature: "(oldProps: PaintProps | undefined, newProps: PaintProps | undefined) => PaintPropsDiff",
+              description: "Get only the changed paint properties (for efficient MapLibre updates)"
+            },
+            {
+              name: "filterEqual",
+              signature: "(a: FilterExpression | undefined, b: FilterExpression | undefined) => boolean",
+              description: "Check if two filter expressions are equal"
+            },
+            {
+              name: "serializeFilter",
+              signature: "(filter: FilterExpression | undefined) => string",
+              description: "Serialize a filter expression for comparison"
+            }
+          ]
+        }
+      }
+    },
+    workers: {
+      importPath: "@classic-homes/maps-core/workers",
+      description: "Web Worker infrastructure for off-main-thread spatial processing",
+      modules: {
+        client: {
+          description: "Client API for communicating with spatial workers",
+          functions: [
+            {
+              name: "SpatialWorkerClient",
+              signature: "class",
+              description: "Client class for interacting with the spatial worker. Handles worker lifecycle, request tracking, and graceful degradation."
+            },
+            {
+              name: "createSpatialWorkerClient",
+              signature: "(options?: SpatialWorkerClientOptions) => SpatialWorkerClient",
+              description: "Factory function to create a spatial worker client"
+            }
+          ],
+          example: "// Vite setup\nimport SpatialWorker from '@classic-homes/maps-core/workers/spatial.worker?worker';\nconst client = createSpatialWorkerClient({\n  workerFactory: () => new SpatialWorker(),\n  useRTree: true,\n});\n\nawait client.initialize(geojsonData);\nconst result = await client.query(viewportBounds);\nclient.terminate();"
+        }
+      }
+    },
+    theme: {
+      importPath: "@classic-homes/maps-core/theme",
+      description: "Theme exports only (for tree-shaking)"
+    },
+    types: {
+      importPath: "@classic-homes/maps-core/types",
+      description: "TypeScript type definitions only"
+    }
+  },
+  types: {
+    props: {
+      description: "Component prop types",
+      types: [
+        {
+          name: "BaseMapProps",
+          description: "Base props shared by all map components",
+          properties: [
+            { name: "title", type: "string", required: true, description: "Accessible title for the map (aria-label)" },
+            { name: "description", type: "string", required: false, description: "Optional description for screen readers" },
+            { name: "width", type: "number | string", required: false, description: "Map width (CSS value or pixels)" },
+            { name: "height", type: "number | string", required: false, description: "Map height (default: 400)" },
+            { name: "minHeight", type: "number", required: false, description: "Minimum height constraint" },
+            { name: "maxHeight", type: "number", required: false, description: "Maximum height constraint" },
+            { name: "loading", type: "boolean", required: false, description: "Show loading skeleton" },
+            { name: "error", type: "string | null", required: false, description: "Error message to display" },
+            { name: "emptyMessage", type: "string", required: false, description: "Message when no data/features" },
+            { name: "theme", type: "'light' | 'dark' | 'auto'", required: false, description: "Theme preference" },
+            { name: "animation", type: "boolean", required: false, description: "Enable animations (respects prefers-reduced-motion)" },
+            { name: "class", type: "string", required: false, description: "Custom CSS class" }
+          ]
+        },
+        {
+          name: "MapProps",
+          description: "Full map component props (extends BaseMapProps)",
+          properties: [
+            { name: "style", type: "string | MapStyleSpec", required: false, description: "Map style URL or style spec object" },
+            { name: "center", type: "[number, number]", required: false, description: "Initial center [lng, lat]" },
+            { name: "zoom", type: "number", required: false, description: "Initial zoom level (0-24)" },
+            { name: "bearing", type: "number", required: false, description: "Initial bearing in degrees" },
+            { name: "pitch", type: "number", required: false, description: "Initial pitch/tilt in degrees" },
+            { name: "bounds", type: "[[number, number], [number, number]]", required: false, description: "Fit to bounds on load" },
+            { name: "boundsPadding", type: "number | { top, right, bottom, left }", required: false, description: "Padding when fitting to bounds" },
+            { name: "minZoom", type: "number", required: false, description: "Minimum zoom level" },
+            { name: "maxZoom", type: "number", required: false, description: "Maximum zoom level" },
+            { name: "maxBounds", type: "BoundsArray", required: false, description: "Maximum bounds the map can pan to" },
+            { name: "interactive", type: "boolean", required: false, description: "Enable map interactions" },
+            { name: "scrollZoom", type: "boolean", required: false, description: "Enable scroll zoom" },
+            { name: "dragPan", type: "boolean", required: false, description: "Enable drag pan" },
+            { name: "dragRotate", type: "boolean", required: false, description: "Enable drag rotate" },
+            { name: "doubleClickZoom", type: "boolean", required: false, description: "Enable double click zoom" },
+            { name: "touchZoomRotate", type: "boolean", required: false, description: "Enable touch zoom/rotate" },
+            { name: "keyboard", type: "boolean", required: false, description: "Enable keyboard navigation" },
+            { name: "navigationControl", type: "boolean", required: false, description: "Show navigation control" },
+            { name: "navigationControlPosition", type: "ControlPosition", required: false, description: "Navigation control position" },
+            { name: "scaleControl", type: "boolean", required: false, description: "Show scale control" },
+            { name: "scaleControlPosition", type: "ControlPosition", required: false, description: "Scale control position" },
+            { name: "fullscreenControl", type: "boolean", required: false, description: "Show fullscreen control" },
+            { name: "geolocateControl", type: "boolean", required: false, description: "Show geolocate control" },
+            { name: "onLoad", type: "(params: MapLoadEventParams) => void", required: false, description: "Callback when map loads" },
+            { name: "onClick", type: "(params: MapClickEventParams) => void", required: false, description: "Callback for map click" },
+            { name: "onMove", type: "(params: MapMoveEventParams) => void", required: false, description: "Callback for map move/pan" },
+            { name: "onZoom", type: "(params: MapMoveEventParams) => void", required: false, description: "Callback for zoom change" },
+            { name: "onError", type: "(params: MapErrorEventParams) => void", required: false, description: "Callback for map errors" }
+          ]
+        },
+        {
+          name: "SourceProps",
+          description: "Props for GeoJSON/vector/raster data sources",
+          properties: [
+            { name: "id", type: "string", required: true, description: "Unique source ID" },
+            { name: "type", type: "'geojson' | 'vector' | 'raster' | 'raster-dem' | 'image' | 'video'", required: true, description: "Source type" },
+            { name: "data", type: "GeoJSONFeatureCollection | string", required: false, description: "Source data (for GeoJSON sources)" },
+            { name: "tiles", type: "string[]", required: false, description: "Tile URL template (for vector/raster)" },
+            { name: "url", type: "string", required: false, description: "TileJSON URL" },
+            { name: "tileSize", type: "number", required: false, description: "Tile size (default: 512)" },
+            { name: "attribution", type: "string", required: false, description: "Attribution text" },
+            { name: "cluster", type: "boolean | ClusterConfig", required: false, description: "Enable clustering (GeoJSON only)" },
+            { name: "clusterRadius", type: "number", required: false, description: "Cluster radius (GeoJSON only)" },
+            { name: "clusterMaxZoom", type: "number", required: false, description: "Max zoom for clustering" },
+            { name: "generateId", type: "boolean", required: false, description: "Generate feature IDs" },
+            { name: "fitBounds", type: "boolean", required: false, description: "Fit map to source bounds when loaded" },
+            { name: "fitBoundsPadding", type: "number | { top, right, bottom, left }", required: false, description: "Padding when fitting" },
+            { name: "fitBoundsMaxZoom", type: "number", required: false, description: "Max zoom when fitting" }
+          ]
+        },
+        {
+          name: "MarkerProps",
+          description: "Props for map markers. NOTE: DOM-based markers (maplibregl.Marker) are susceptible to CSS framework interference that can cause visual sliding during map pan/rotate operations. For production use cases requiring markers, consider using SymbolLayer instead, which renders on the GPU canvas and is immune to CSS interference.",
+          properties: [
+            { name: "id", type: "string", required: false, description: "Unique marker ID" },
+            { name: "coordinates", type: "[number, number]", required: true, description: "Marker position [lng, lat]" },
+            { name: "color", type: "string", required: false, description: "Marker color" },
+            { name: "anchor", type: "'center' | 'top' | 'bottom' | 'left' | 'right' | ...", required: false, description: "Custom anchor point" },
+            { name: "offset", type: "[number, number]", required: false, description: "Offset from coordinates in pixels" },
+            { name: "rotation", type: "number", required: false, description: "Marker rotation angle" },
+            { name: "draggable", type: "boolean", required: false, description: "Enable dragging" },
+            { name: "scale", type: "number", required: false, description: "Marker scale" },
+            { name: "onClick", type: "(params: MarkerClickEventParams) => void", required: false, description: "Callback for marker click" },
+            { name: "onDrag", type: "(params: MarkerDragEventParams) => void", required: false, description: "Callback for marker drag" },
+            { name: "onDragEnd", type: "(params: MarkerDragEventParams) => void", required: false, description: "Callback when drag ends" }
+          ]
+        },
+        {
+          name: "PopupProps",
+          description: "Props for map popups",
+          properties: [
+            { name: "coordinates", type: "[number, number]", required: true, description: "Popup position [lng, lat]" },
+            { name: "closeButton", type: "boolean", required: false, description: "Show close button (default: true)" },
+            { name: "closeOnClick", type: "boolean", required: false, description: "Close on click outside (default: true)" },
+            { name: "closeOnMove", type: "boolean", required: false, description: "Close when map moves" },
+            { name: "anchor", type: "'center' | 'top' | 'bottom' | 'left' | 'right' | ...", required: false, description: "Popup anchor" },
+            { name: "offset", type: "number | [number, number]", required: false, description: "Popup offset" },
+            { name: "maxWidth", type: "string", required: false, description: "Maximum width (default: '300px')" },
+            { name: "focusAfterOpen", type: "boolean", required: false, description: "Focus popup when opened" },
+            { name: "autoPan", type: "boolean", required: false, description: "Auto-pan to ensure popup is visible (default: true)" },
+            { name: "autoPanPadding", type: "number | { top, right, bottom, left }", required: false, description: "Padding around popup when auto-panning" },
+            { name: "onOpen", type: "(params: PopupEventParams) => void", required: false, description: "Callback when popup opens" },
+            { name: "onClose", type: "(params: PopupEventParams) => void", required: false, description: "Callback when popup closes" }
+          ]
+        },
+        {
+          name: "BaseLayerProps",
+          description: "Base props shared by all layer components",
+          properties: [
+            { name: "id", type: "string", required: true, description: "Unique layer ID" },
+            { name: "source", type: "string", required: true, description: "Source ID this layer uses" },
+            { name: "sourceLayer", type: "string", required: false, description: "Source layer (for vector tile sources)" },
+            { name: "visible", type: "boolean", required: false, description: "Layer visibility" },
+            { name: "opacity", type: "number", required: false, description: "Layer opacity (0-1)" },
+            { name: "minZoom", type: "number", required: false, description: "Minimum zoom level" },
+            { name: "maxZoom", type: "number", required: false, description: "Maximum zoom level" },
+            { name: "filter", type: "unknown[]", required: false, description: "Filter expression for features" },
+            { name: "beforeId", type: "string", required: false, description: "Insert layer before another" },
+            { name: "onClick", type: "(params: FeatureClickEventParams) => void", required: false, description: "Callback for feature click" },
+            { name: "onHover", type: "(params: FeatureHoverEventParams) => void", required: false, description: "Callback for feature hover" }
+          ]
+        },
+        {
+          name: "FillLayerProps",
+          description: "Props for polygon fill layers (extends BaseLayerProps)",
+          properties: [
+            { name: "fillColor", type: "string | Expression", required: false, description: "Fill color" },
+            { name: "fillOpacity", type: "number | Expression", required: false, description: "Fill opacity (0-1)" },
+            { name: "fillOutlineColor", type: "string | Expression", required: false, description: "Outline color" },
+            { name: "fillPattern", type: "string", required: false, description: "Fill pattern (sprite image name)" },
+            { name: "fillTranslate", type: "[number, number]", required: false, description: "Translate fill geometry" },
+            { name: "fillAntialias", type: "boolean", required: false, description: "Fill antialias" }
+          ]
+        },
+        {
+          name: "LineLayerProps",
+          description: "Props for line layers (extends BaseLayerProps)",
+          properties: [
+            { name: "lineColor", type: "string | Expression", required: false, description: "Line color" },
+            { name: "lineWidth", type: "number | Expression", required: false, description: "Line width in pixels" },
+            { name: "lineOpacity", type: "number | Expression", required: false, description: "Line opacity (0-1)" },
+            { name: "lineCap", type: "'butt' | 'round' | 'square'", required: false, description: "Line cap style" },
+            { name: "lineJoin", type: "'bevel' | 'round' | 'miter'", required: false, description: "Line join style" },
+            { name: "lineDasharray", type: "number[]", required: false, description: "Dash pattern" },
+            { name: "lineGapWidth", type: "number", required: false, description: "Line gap width" },
+            { name: "lineOffset", type: "number", required: false, description: "Line offset" }
+          ]
+        },
+        {
+          name: "CircleLayerProps",
+          description: "Props for circle point layers (extends BaseLayerProps)",
+          properties: [
+            { name: "circleRadius", type: "number | Expression", required: false, description: "Circle radius in pixels" },
+            { name: "circleColor", type: "string | Expression", required: false, description: "Circle color" },
+            { name: "circleOpacity", type: "number | Expression", required: false, description: "Circle opacity (0-1)" },
+            { name: "circleStrokeWidth", type: "number | Expression", required: false, description: "Stroke width" },
+            { name: "circleStrokeColor", type: "string | Expression", required: false, description: "Stroke color" },
+            { name: "circleBlur", type: "number", required: false, description: "Circle blur" },
+            { name: "circlePitchAlignment", type: "'map' | 'viewport'", required: false, description: "Pitch alignment" }
+          ]
+        },
+        {
+          name: "SymbolLayerProps",
+          description: "Props for symbol/label layers (extends BaseLayerProps)",
+          properties: [
+            { name: "iconImage", type: "string | Expression", required: false, description: "Icon image name (from sprite)" },
+            { name: "iconSize", type: "number | Expression", required: false, description: "Icon size" },
+            { name: "iconRotate", type: "number | Expression", required: false, description: "Icon rotation angle" },
+            { name: "iconOffset", type: "[number, number]", required: false, description: "Icon offset" },
+            { name: "iconAnchor", type: "'center' | 'left' | 'right' | 'top' | 'bottom' | ...", required: false, description: "Icon anchor" },
+            { name: "iconAllowOverlap", type: "boolean", required: false, description: "Allow icon overlap" },
+            { name: "textField", type: "string | Expression", required: false, description: "Text field content" },
+            { name: "textFont", type: "string[]", required: false, description: "Text font stack" },
+            { name: "textSize", type: "number | Expression", required: false, description: "Text size" },
+            { name: "textColor", type: "string | Expression", required: false, description: "Text color" },
+            { name: "textHaloColor", type: "string", required: false, description: "Text halo color" },
+            { name: "textHaloWidth", type: "number", required: false, description: "Text halo width" },
+            { name: "textAnchor", type: "'center' | 'left' | 'right' | 'top' | 'bottom' | ...", required: false, description: "Text anchor" },
+            { name: "symbolPlacement", type: "'point' | 'line' | 'line-center'", required: false, description: "Symbol placement" }
+          ]
+        },
+        {
+          name: "FillExtrusionLayerProps",
+          description: "Props for 3D extrusion layers (extends BaseLayerProps)",
+          properties: [
+            { name: "fillExtrusionHeight", type: "number | Expression", required: true, description: "Extrusion height in meters" },
+            { name: "fillExtrusionBase", type: "number | Expression", required: false, description: "Base height in meters" },
+            { name: "fillExtrusionColor", type: "string | Expression", required: false, description: "Extrusion color" },
+            { name: "fillExtrusionOpacity", type: "number", required: false, description: "Extrusion opacity (0-1)" },
+            { name: "fillExtrusionVerticalGradient", type: "boolean", required: false, description: "Enable vertical gradient" }
+          ]
+        },
+        {
+          name: "HeatmapLayerProps",
+          description: "Props for heatmap layers (extends BaseLayerProps)",
+          properties: [
+            { name: "heatmapRadius", type: "number | Expression", required: false, description: "Heatmap radius in pixels" },
+            { name: "heatmapIntensity", type: "number | Expression", required: false, description: "Intensity multiplier" },
+            { name: "heatmapWeight", type: "number | Expression", required: false, description: "Weight per point" },
+            { name: "heatmapColor", type: "Expression", required: false, description: "Heatmap color ramp expression" },
+            { name: "heatmapOpacity", type: "number | Expression", required: false, description: "Heatmap opacity" }
+          ]
+        },
+        {
+          name: "RasterLayerProps",
+          description: "Props for raster/image layers (extends BaseLayerProps)",
+          properties: [
+            { name: "rasterOpacity", type: "number", required: false, description: "Raster opacity (0-1)" },
+            { name: "rasterHueRotate", type: "number", required: false, description: "Hue rotation in degrees" },
+            { name: "rasterBrightnessMin", type: "number", required: false, description: "Minimum brightness (0-1)" },
+            { name: "rasterBrightnessMax", type: "number", required: false, description: "Maximum brightness (0-1)" },
+            { name: "rasterSaturation", type: "number", required: false, description: "Saturation adjustment (-1 to 1)" },
+            { name: "rasterContrast", type: "number", required: false, description: "Contrast adjustment (-1 to 1)" },
+            { name: "rasterResampling", type: "'linear' | 'nearest'", required: false, description: "Resampling method" },
+            { name: "rasterFadeDuration", type: "number", required: false, description: "Fade duration when tiles load (ms)" }
+          ]
+        },
+        {
+          name: "LegendProps",
+          description: "Props for map legend component",
+          properties: [
+            { name: "title", type: "string", required: false, description: "Legend title" },
+            { name: "position", type: "ControlPosition", required: false, description: "Position on map" },
+            { name: "type", type: "'categorical' | 'gradient'", required: false, description: "Legend type" },
+            { name: "items", type: "LegendItem[]", required: false, description: "Items for categorical legends" },
+            { name: "gradient", type: "GradientStop[]", required: false, description: "Gradient stops for continuous legends" },
+            { name: "minLabel", type: "string", required: false, description: "Min value label for gradient" },
+            { name: "maxLabel", type: "string", required: false, description: "Max value label for gradient" },
+            { name: "collapsible", type: "boolean", required: false, description: "Whether legend is collapsible" },
+            { name: "collapsed", type: "boolean", required: false, description: "Whether initially collapsed" },
+            { name: "onItemClick", type: "(item: LegendItem, index: number) => void", required: false, description: "Callback for item click" }
+          ]
+        },
+        {
+          name: "LegendGroupProps",
+          description: "Props for accordion-style legend container",
+          properties: [
+            { name: "legends", type: "LegendConfig[]", required: true, description: "Array of legend configurations" },
+            { name: "position", type: "ControlPosition", required: false, description: "Position on map" },
+            { name: "defaultExpanded", type: "string", required: false, description: "ID of initially expanded legend" },
+            { name: "expanded", type: "string | null", required: false, description: "Controlled expanded state" },
+            { name: "onExpandedChange", type: "(id: string | null) => void", required: false, description: "Callback when expanded changes" },
+            { name: "allowCollapseAll", type: "boolean", required: false, description: "Allow collapsing all (default: false)" }
+          ]
+        },
+        {
+          name: "CoordinateDisplayProps",
+          description: "Props for coordinate display control",
+          properties: [
+            { name: "position", type: "ControlPosition", required: false, description: "Position on map" },
+            { name: "format", type: "'decimal' | 'dms' | 'dd'", required: false, description: "Coordinate format" },
+            { name: "precision", type: "number", required: false, description: "Decimal places" },
+            { name: "showZoom", type: "boolean", required: false, description: "Show zoom level" },
+            { name: "showBearing", type: "boolean", required: false, description: "Show bearing" }
+          ]
+        },
+        {
+          name: "NavigationControlProps",
+          description: "Props for navigation control",
+          properties: [
+            { name: "position", type: "ControlPosition", required: false, description: "Position on map" },
+            { name: "showCompass", type: "boolean", required: false, description: "Show compass" },
+            { name: "showZoom", type: "boolean", required: false, description: "Show zoom buttons" },
+            { name: "visualizePitch", type: "boolean", required: false, description: "Visualize pitch with compass" }
+          ]
+        },
+        {
+          name: "ScaleControlProps",
+          description: "Props for scale control",
+          properties: [
+            { name: "position", type: "ControlPosition", required: false, description: "Position on map" },
+            { name: "maxWidth", type: "number", required: false, description: "Maximum width of scale" },
+            { name: "unit", type: "'imperial' | 'metric' | 'nautical'", required: false, description: "Unit system" }
+          ]
+        },
+        {
+          name: "GeolocateControlProps",
+          description: "Props for geolocate control",
+          properties: [
+            { name: "position", type: "ControlPosition", required: false, description: "Position on map" },
+            { name: "trackUserLocation", type: "boolean", required: false, description: "Track user location" },
+            { name: "showAccuracyCircle", type: "boolean", required: false, description: "Show accuracy circle" },
+            { name: "showUserHeading", type: "boolean", required: false, description: "Show user heading" }
+          ]
+        }
+      ]
+    },
+    data: {
+      description: "Data structure types",
+      types: [
+        {
+          name: "LngLat",
+          description: "Longitude/latitude coordinate pair as [lng, lat] tuple"
+        },
+        {
+          name: "MapBounds",
+          description: "Geographic bounding box with southwest and northeast corners",
+          properties: [
+            { name: "southwest", type: "LngLat", required: true, description: "Southwest corner" },
+            { name: "northeast", type: "LngLat", required: true, description: "Northeast corner" }
+          ]
+        },
+        {
+          name: "BoundsArray",
+          description: "Bounding box as [[sw_lng, sw_lat], [ne_lng, ne_lat]]"
+        },
+        {
+          name: "MapViewport",
+          description: "Map viewport state (center, zoom, bearing, pitch)"
+        },
+        {
+          name: "GeoJSONFeature",
+          description: "GeoJSON Feature with typed properties"
+        },
+        {
+          name: "GeoJSONFeatureCollection",
+          description: "GeoJSON FeatureCollection with typed features"
+        },
+        {
+          name: "GeoJSONGeometry",
+          description: "Union of all GeoJSON geometry types"
+        },
+        {
+          name: "MarkerData",
+          description: "Data for map markers",
+          properties: [
+            { name: "id", type: "string | number", required: true, description: "Unique identifier" },
+            { name: "coordinates", type: "LngLat", required: true, description: "Marker position" },
+            { name: "label", type: "string", required: false, description: "Display label" },
+            { name: "color", type: "string", required: false, description: "Marker color" }
+          ]
+        },
+        {
+          name: "ClusterConfig",
+          description: "Configuration for source clustering",
+          properties: [
+            { name: "radius", type: "number", required: false, description: "Cluster radius in pixels" },
+            { name: "maxZoom", type: "number", required: false, description: "Max zoom for clustering" },
+            { name: "minPoints", type: "number", required: false, description: "Minimum points to form cluster" }
+          ]
+        },
+        {
+          name: "ClusterFeatureProperties",
+          description: "Properties automatically added to cluster features by MapLibre",
+          properties: [
+            { name: "cluster_id", type: "number", required: true, description: "Unique cluster identifier" },
+            { name: "point_count", type: "number", required: true, description: "Number of points in cluster" },
+            { name: "point_count_abbreviated", type: "string", required: true, description: "Abbreviated count (e.g., '1.2k')" },
+            { name: "cluster", type: "true", required: true, description: "Whether this is a cluster" }
+          ]
+        },
+        {
+          name: "LegendItem",
+          description: "Item for categorical legends",
+          properties: [
+            { name: "label", type: "string", required: true, description: "Item label" },
+            { name: "color", type: "string", required: true, description: "Item color" },
+            { name: "icon", type: "string", required: false, description: "Optional icon name" },
+            { name: "value", type: "string | number", required: false, description: "Optional value" },
+            { name: "active", type: "boolean", required: false, description: "Whether active/visible" }
+          ]
+        },
+        {
+          name: "GradientStop",
+          description: "Stop for gradient legends",
+          properties: [
+            { name: "position", type: "number", required: true, description: "Position in gradient (0-1)" },
+            { name: "color", type: "string", required: true, description: "Color at position" },
+            { name: "label", type: "string", required: false, description: "Optional label" }
+          ]
+        },
+        {
+          name: "ControlPosition",
+          description: "Position for map controls: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'"
+        },
+        {
+          name: "LoadGeoJSONOptions",
+          description: "Options for loadGeoJSON function",
+          properties: [
+            { name: "timeout", type: "number", required: false, description: "Request timeout in ms (default: 30000)" },
+            { name: "fetchOptions", type: "RequestInit", required: false, description: "Additional fetch options" },
+            { name: "validate", type: "boolean", required: false, description: "Validate structure after loading" }
+          ]
+        },
+        {
+          name: "ValidationResult",
+          description: "Result of GeoJSON validation",
+          properties: [
+            { name: "valid", type: "boolean", required: true, description: "Whether valid" },
+            { name: "errors", type: "string[]", required: true, description: "List of errors" },
+            { name: "featureCount", type: "number", required: false, description: "Number of features" },
+            { name: "geometryTypes", type: "string[]", required: false, description: "Geometry types found" }
+          ]
+        },
+        {
+          name: "ClusterExpandOptions",
+          description: "Options for cluster expansion",
+          properties: [
+            { name: "duration", type: "number", required: false, description: "Animation duration in ms (default: 500)" },
+            { name: "animate", type: "boolean", required: false, description: "Whether to animate (default: true)" },
+            { name: "padding", type: "number | { top, bottom, left, right }", required: false, description: "Padding around bounds" },
+            { name: "maxZoom", type: "number", required: false, description: "Maximum zoom level" }
+          ]
+        },
+        {
+          name: "GeoJSONFingerprint",
+          description: "Lightweight fingerprint for fast GeoJSON equality checking",
+          properties: [
+            { name: "type", type: "string", required: true, description: "GeoJSON type (FeatureCollection, Feature, etc.)" },
+            { name: "featureCount", type: "number", required: true, description: "Number of features" },
+            { name: "firstFeatureId", type: "string | number | undefined", required: false, description: "ID of first feature" },
+            { name: "lastFeatureId", type: "string | number | undefined", required: false, description: "ID of last feature" },
+            { name: "geometryTypes", type: "Set<string>", required: true, description: "Set of geometry types present" }
+          ]
+        },
+        {
+          name: "PaintProps",
+          description: "MapLibre paint properties object (Record<string, unknown>)"
+        },
+        {
+          name: "PaintPropsDiff",
+          description: "Result of comparing two paint prop objects",
+          properties: [
+            { name: "hasChanges", type: "boolean", required: true, description: "Whether any properties changed" },
+            { name: "changed", type: "Record<string, unknown>", required: true, description: "Properties that changed (key -> new value)" },
+            { name: "removed", type: "string[]", required: true, description: "Properties that were removed" }
+          ]
+        },
+        {
+          name: "FilterExpression",
+          description: "MapLibre filter expression (unknown[] | undefined)"
+        },
+        {
+          name: "SpatialIndex",
+          description: "Grid-based spatial index for viewport queries",
+          properties: [
+            { name: "cells", type: "Map<string, GeoJSONFeature[]>", required: true, description: "Grid cells containing features" },
+            { name: "bounds", type: "BoundsArray", required: true, description: "Total bounds of indexed data" },
+            { name: "cellSize", type: "{ lng: number; lat: number }", required: true, description: "Size of each grid cell" },
+            { name: "featureCount", type: "number", required: true, description: "Total number of features indexed" }
+          ]
+        },
+        {
+          name: "RTreeIndex",
+          description: "R-tree spatial index (better for clustered data)",
+          properties: [
+            { name: "tree", type: "RBush<RTreeItem>", required: true, description: "R-tree data structure" },
+            { name: "bounds", type: "BoundsArray", required: true, description: "Total bounds of indexed data" },
+            { name: "featureCount", type: "number", required: true, description: "Total number of features indexed" }
+          ]
+        },
+        {
+          name: "QueryStats",
+          description: "Statistics from a spatial query",
+          properties: [
+            { name: "totalFeatures", type: "number", required: true, description: "Total features in index" },
+            { name: "visibleFeatures", type: "number", required: true, description: "Features in query result" },
+            { name: "culledPercent", type: "number", required: true, description: "Percentage of features culled" },
+            { name: "cellsChecked", type: "number", required: true, description: "Number of grid cells checked" },
+            { name: "totalCells", type: "number", required: true, description: "Total cells in grid" }
+          ]
+        },
+        {
+          name: "PanVelocity",
+          description: "Velocity vector for predictive panning",
+          properties: [
+            { name: "lngPerSec", type: "number", required: true, description: "Longitude change per second" },
+            { name: "latPerSec", type: "number", required: true, description: "Latitude change per second" },
+            { name: "magnitude", type: "number", required: true, description: "Velocity magnitude" }
+          ]
+        },
+        {
+          name: "LODData",
+          description: "Level-of-Detail data structure",
+          properties: [
+            { name: "levels", type: "Map<number, GeoJSONFeatureCollection>", required: true, description: "Data at each zoom level" },
+            { name: "zoomThresholds", type: "number[]", required: true, description: "Zoom level breakpoints" },
+            { name: "originalFeatureCount", type: "number", required: true, description: "Original feature count" }
+          ]
+        },
+        {
+          name: "SimplificationStats",
+          description: "Statistics from polygon simplification",
+          properties: [
+            { name: "originalPoints", type: "number", required: true, description: "Original point count" },
+            { name: "simplifiedPoints", type: "number", required: true, description: "Point count after simplification" },
+            { name: "reductionPercent", type: "number", required: true, description: "Percentage of points removed" },
+            { name: "processingTimeMs", type: "number", required: true, description: "Time taken in milliseconds" }
+          ]
+        },
+        {
+          name: "SpatialWorkerClientOptions",
+          description: "Options for creating a SpatialWorkerClient",
+          properties: [
+            { name: "requestTimeout", type: "number", required: false, description: "Timeout for requests in ms (default: 30000)" },
+            { name: "useRTree", type: "boolean", required: false, description: "Use R-tree (true) or grid index (false). Default: true" },
+            { name: "gridTargetCells", type: "number", required: false, description: "Target cells for grid index. Default: 1024" },
+            { name: "rtreeMaxEntries", type: "number", required: false, description: "Max entries per R-tree node. Default: 9" },
+            { name: "workerFactory", type: "() => Worker", required: false, description: "Factory function to create the worker" },
+            { name: "workerUrl", type: "string | URL", required: false, description: "URL to the worker script (alternative to workerFactory)" }
+          ]
+        },
+        {
+          name: "WorkerQueryResult",
+          description: "Result from a worker viewport query",
+          properties: [
+            { name: "success", type: "boolean", required: true, description: "Whether query succeeded" },
+            { name: "data", type: "GeoJSONFeatureCollection", required: true, description: "Query results" },
+            { name: "stats", type: "QueryStats", required: true, description: "Query statistics" },
+            { name: "queryTimeMs", type: "number", required: true, description: "Time taken in milliseconds" },
+            { name: "error", type: "string", required: false, description: "Error message if failed" }
+          ]
+        }
+      ]
+    },
+    events: {
+      description: "Event types",
+      types: [
+        {
+          name: "BaseMapEventParams",
+          description: "Base event parameters shared across all map events",
+          properties: [
+            { name: "type", type: "string", required: true, description: "Event type identifier" },
+            { name: "originalEvent", type: "MouseEvent | TouchEvent", required: false, description: "Original native event" }
+          ]
+        },
+        {
+          name: "MapClickEventParams",
+          description: "Parameters for map click events",
+          properties: [
+            { name: "type", type: "'click' | 'dblclick' | 'contextmenu'", required: true, description: "Event type" },
+            { name: "lngLat", type: "LngLat", required: true, description: "Click location [lng, lat]" },
+            { name: "point", type: "[number, number]", required: true, description: "Screen pixel coordinates [x, y]" },
+            { name: "features", type: "GeoJSONFeature[]", required: false, description: "Features at click point" }
+          ]
+        },
+        {
+          name: "MapHoverEventParams",
+          description: "Parameters for mouse move/hover events",
+          properties: [
+            { name: "type", type: "'mousemove' | 'mouseenter' | 'mouseleave'", required: true, description: "Event type" },
+            { name: "lngLat", type: "LngLat", required: true, description: "Cursor location [lng, lat]" },
+            { name: "point", type: "[number, number]", required: true, description: "Screen pixel coordinates [x, y]" },
+            { name: "features", type: "GeoJSONFeature[]", required: false, description: "Features at cursor location" }
+          ]
+        },
+        {
+          name: "FeatureClickEventParams",
+          description: "Parameters for feature click events",
+          properties: [
+            { name: "type", type: "'click' | 'dblclick' | 'contextmenu'", required: true, description: "Event type" },
+            { name: "feature", type: "GeoJSONFeature", required: true, description: "Clicked feature" },
+            { name: "featureId", type: "string | number", required: false, description: "Feature ID" },
+            { name: "layerId", type: "string", required: true, description: "Layer ID" },
+            { name: "sourceId", type: "string", required: true, description: "Source ID" },
+            { name: "lngLat", type: "LngLat", required: true, description: "Click location" },
+            { name: "point", type: "[number, number]", required: true, description: "Screen coordinates" }
+          ]
+        },
+        {
+          name: "FeatureHoverEventParams",
+          description: "Parameters for feature hover events",
+          properties: [
+            { name: "type", type: "'mouseenter' | 'mousemove' | 'mouseleave'", required: true, description: "Event type" },
+            { name: "feature", type: "GeoJSONFeature | null", required: true, description: "Hovered feature (null on leave)" },
+            { name: "featureId", type: "string | number", required: false, description: "Feature ID" },
+            { name: "layerId", type: "string", required: true, description: "Layer ID" },
+            { name: "sourceId", type: "string", required: true, description: "Source ID" },
+            { name: "lngLat", type: "LngLat", required: true, description: "Cursor location" }
+          ]
+        },
+        {
+          name: "MarkerClickEventParams",
+          description: "Parameters for marker click events",
+          properties: [
+            { name: "type", type: "'click'", required: true, description: "Event type" },
+            { name: "markerId", type: "string", required: true, description: "Marker ID" },
+            { name: "lngLat", type: "LngLat", required: true, description: "Marker coordinates" },
+            { name: "properties", type: "Record<string, unknown>", required: false, description: "Marker properties" }
+          ]
+        },
+        {
+          name: "MarkerDragEventParams",
+          description: "Parameters for marker drag events",
+          properties: [
+            { name: "type", type: "'dragstart' | 'drag' | 'dragend'", required: true, description: "Event type" },
+            { name: "markerId", type: "string", required: true, description: "Marker ID" },
+            { name: "lngLat", type: "LngLat", required: true, description: "Current coordinates" },
+            { name: "originalLngLat", type: "LngLat", required: false, description: "Original coordinates at drag start" }
+          ]
+        },
+        {
+          name: "MapLoadEventParams",
+          description: "Parameters for map load events",
+          properties: [
+            { name: "type", type: "'load' | 'style.load' | 'idle'", required: true, description: "Event type" },
+            { name: "loaded", type: "boolean", required: true, description: "Whether fully loaded" }
+          ]
+        },
+        {
+          name: "MapMoveEventParams",
+          description: "Parameters for map move events",
+          properties: [
+            { name: "type", type: "'move' | 'movestart' | 'moveend' | 'zoom' | ...", required: true, description: "Event type" },
+            { name: "center", type: "LngLat", required: true, description: "New center" },
+            { name: "zoom", type: "number", required: true, description: "New zoom level" },
+            { name: "bearing", type: "number", required: true, description: "New bearing" },
+            { name: "pitch", type: "number", required: true, description: "New pitch" },
+            { name: "isUserInteraction", type: "boolean", required: false, description: "Whether user-initiated" }
+          ]
+        },
+        {
+          name: "PopupEventParams",
+          description: "Parameters for popup events",
+          properties: [
+            { name: "type", type: "'open' | 'close'", required: true, description: "Event type" },
+            { name: "lngLat", type: "LngLat", required: true, description: "Popup coordinates" }
+          ]
+        },
+        {
+          name: "MapErrorEventParams",
+          description: "Parameters for map error events",
+          properties: [
+            { name: "type", type: "'error'", required: true, description: "Event type" },
+            { name: "message", type: "string", required: true, description: "Error message" },
+            { name: "source", type: "string", required: false, description: "Error source (tile, source, layer)" },
+            { name: "error", type: "Error", required: false, description: "Original error object" }
+          ]
+        }
+      ]
+    }
+  },
+  components: {
+    react: {
+      package: "@classic-homes/maps-react",
+      components: [
+        "Map",
+        "MapContext",
+        "MapContainer",
+        "MapSkeleton",
+        "MapError",
+        "MapEmpty",
+        "Source",
+        "Marker",
+        "Popup",
+        "PopupCard",
+        "PopupHeader",
+        "PopupContent",
+        "PopupFooter",
+        "FillLayer",
+        "LineLayer",
+        "CircleLayer",
+        "SymbolLayer",
+        "FillExtrusionLayer",
+        "HeatmapLayer",
+        "RasterLayer",
+        "Legend",
+        "LegendGroup",
+        "CoordinateDisplay",
+        "DeckOverlay"
+      ],
+      hooks: [
+        {
+          name: "useMap",
+          signature: "() => MapContextValue",
+          description: "Hook to access the MapLibre map instance and state from context. Must be used within a Map component.",
+          returns: "{ map: MapLibreMap | null, loaded: boolean, controlOffsets?: ControlOffsets, registerControl?, unregisterControl?, getCustomControlOffset? }"
+        },
+        {
+          name: "useMapInstance",
+          signature: "() => MapLibreMap | null",
+          description: "Hook to access the map instance only when loaded. Returns null if map is not yet available."
+        },
+        {
+          name: "useMapTheme",
+          signature: "(theme?: 'light' | 'dark' | 'auto') => { resolvedTheme: 'light' | 'dark', mapTheme: MapTheme, mapStyle: StyleSpecification }",
+          description: "Hook to get the resolved theme based on preference and system settings. Handles 'auto' mode by detecting system dark mode."
+        },
+        {
+          name: "useReducedMotion",
+          signature: "() => boolean",
+          description: "Hook to detect if user prefers reduced motion. Returns true if prefers-reduced-motion media query matches."
+        },
+        {
+          name: "useLayer",
+          signature: "(options: UseLayerOptions) => void",
+          description: "Hook for adding custom layers to the map. Handles layer lifecycle (add/update/remove) automatically."
+        }
+      ],
+      context: {
+        name: "MapContext",
+        description: "React context for sharing map instance with child components",
+        value: {
+          map: "MapLibreMap | null - The MapLibre map instance",
+          loaded: "boolean - Whether the map has loaded",
+          controlOffsets: "Record<string, number> - Pixel offsets for custom controls",
+          registerControl: "(id, position, height) => number - Register a custom control",
+          unregisterControl: "(id, position) => void - Unregister a custom control",
+          getCustomControlOffset: "(id, position) => number - Get vertical offset for a control"
+        }
+      }
+    },
+    svelte: {
+      package: "@classic-homes/maps-svelte",
+      components: [
+        "Map",
+        "MapContainer",
+        "MapSkeleton",
+        "MapError",
+        "MapEmpty",
+        "Source",
+        "Marker",
+        "Popup",
+        "PopupCard",
+        "PopupHeader",
+        "PopupContent",
+        "PopupFooter",
+        "FillLayer",
+        "LineLayer",
+        "CircleLayer",
+        "SymbolLayer",
+        "FillExtrusionLayer",
+        "HeatmapLayer",
+        "RasterLayer",
+        "Legend",
+        "LegendGroup",
+        "CoordinateDisplay",
+        "DeckOverlay"
+      ],
+      composables: [
+        {
+          name: "useMapContext",
+          signature: "() => { map: Writable<Map | null>, loaded: Writable<boolean> }",
+          description: "Get the map context from the parent Map component using Svelte context API"
+        },
+        {
+          name: "useMapTheme",
+          signature: "(theme?: 'light' | 'dark' | 'auto') => { resolvedTheme: 'light' | 'dark', mapTheme: MapTheme, mapStyle: StyleSpecification }",
+          description: "Composable to get the resolved theme based on preference and system settings"
+        },
+        {
+          name: "useReducedMotion",
+          signature: "() => boolean",
+          description: "Composable to detect if user prefers reduced motion"
+        },
+        {
+          name: "useLayer",
+          signature: "(options: UseLayerOptions) => void",
+          description: "Composable for adding custom layers to the map with automatic lifecycle management"
+        }
+      ]
+    }
+  },
+  quickReference: {
+    installation: "npm install @classic-homes/maps-svelte maplibre-gl\n# or\nnpm install @classic-homes/maps-react maplibre-gl",
+    basicUsage: `import { Map, Source, CircleLayer, Marker, Popup } from '@classic-homes/maps-svelte';
+
+<Map
+  title="My Map"
+  center={[-122.4, 37.8]}
+  zoom={10}
+  height={400}
+  navigationControl
+>
+  <Source id="points" data={geojson}>
+    <CircleLayer id="points-layer" source="points" circleRadius={6} circleColor="#3ba4a7" />
+  </Source>
+  <Marker coordinates={[-122.4, 37.8]} color="red" />
+</Map>`,
+    peerDependency: "maplibre-gl@^4.0.0 || ^5.0.0",
+    optionalPeerDependencies: "@deck.gl/core, @deck.gl/layers, @deck.gl/mapbox (for DeckOverlay)",
+    cssImportOrder: "/* In main CSS file - order matters */\n@import '@classic-homes/theme-styles';\n@import 'maplibre-gl/dist/maplibre-gl.css';\n@import '@classic-homes/maps-core/styles/controls.css';\n@import '@classic-homes/maps-core/styles/popup.css';\n\n@tailwind base;\n@tailwind components;\n@tailwind utilities;",
+    tailwindConfig: "module.exports = {\n  presets: [require('@classic-homes/theme-tailwind-preset')],\n  content: [\n    './src/**/*.{js,ts,jsx,tsx}',\n    './node_modules/@classic-homes/maps-react/dist/**/*.{js,mjs}',\n  ],\n};"
+  },
+  bestPractices: {
+    description: "Recommended patterns for using the maps packages effectively",
+    accessibility: {
+      title: "Accessibility",
+      guidelines: [
+        "Always provide a descriptive `title` prop for the Map component - this becomes the aria-label",
+        "Use `description` prop for additional context for screen readers",
+        "The map supports full keyboard navigation: Arrow keys to pan, +/- to zoom, Shift+Arrow to rotate",
+        "Use `generateMapDescription()` utility for dynamic accessible descriptions",
+        "Markers and layers support `ariaLabel` for individual feature descriptions",
+        "Consider providing a text alternative or data table for complex visualizations"
+      ]
+    },
+    performance: {
+      title: "Performance",
+      guidelines: [
+        "Use clustering for large point datasets (>1000 points) via Source's `cluster` prop",
+        "Set `generateId={true}` on Source when using feature state for hover/selection",
+        "Use `minZoom` and `maxZoom` on layers to reduce rendering at unnecessary zoom levels",
+        "Prefer GeoJSON data URLs over inline data for large datasets (enables caching)",
+        "Use `loadGeoJSON()` utility for type-safe data loading with timeout handling",
+        "Memoize GeoJSON data in React to prevent unnecessary re-renders",
+        "For 100k+ features, use `buildSpatialIndex()` or `buildRTreeIndex()` for fast viewport culling",
+        "Use `createGeoJSONFingerprint()` for O(1) equality checks instead of deep comparison",
+        "Use `getChangedPaintProps()` to only update changed paint properties (minimizes MapLibre API calls)",
+        "Consider `createIdleViewportManager()` for smooth panning with deferred updates",
+        "Use `createPredictiveViewportManager()` to eliminate feature pop-in during panning",
+        "For very large polygons, use LOD utilities with `simplifyPolygon()` for zoom-based simplification",
+        "Use `SpatialWorkerClient` to move spatial indexing off the main thread for 100k+ features",
+        "Set `hoverThrottleMs` on layers to throttle hover callbacks (feature-state updates remain immediate)"
+      ]
+    },
+    theming: {
+      title: "Theming",
+      guidelines: [
+        "Use `theme='auto'` to automatically respect system dark/light preference",
+        "All map UI elements (controls, popups, legends) inherit from design tokens",
+        "Use `useMapTheme` hook to access resolved theme and style in custom components",
+        "The `useReducedMotion` hook respects user's motion preferences for animations",
+        "Custom layers can use theme colors via the `MapTheme` object from the hook"
+      ]
+    },
+    layerOrdering: {
+      title: "Layer Ordering",
+      guidelines: [
+        "Layers render in the order they appear in JSX/template",
+        "Use `beforeId` prop to insert layers at specific positions",
+        "Common order: Fill layers -> Line layers -> Circle layers -> Symbol layers",
+        "Place highlight/selection layers after base layers",
+        "Use z-index style properties within layer types for fine control"
+      ]
+    },
+    eventHandling: {
+      title: "Event Handling",
+      guidelines: [
+        "Use layer-level `onClick` and `onHover` for feature interactions (more efficient than map-level)",
+        "Feature events include full feature properties and geometry",
+        "Use `feature.id` for feature state operations (hover highlighting)",
+        "Marker events include marker-specific data and coordinates",
+        "Map events provide viewport info (center, zoom, bearing, pitch)"
+      ]
+    },
+    clustering: {
+      title: "Clustering",
+      guidelines: [
+        "Enable via `<Source cluster={true}>` or with config: `cluster={{ radius: 50, maxZoom: 14 }}`",
+        "Use `isClusterFeature()` type guard to check if a feature is a cluster",
+        "Use `expandCluster()` to zoom into clusters on click",
+        "Cluster features have `cluster_id`, `point_count`, and `point_count_abbreviated` properties",
+        "Style clusters differently using data-driven expressions based on `point_count`"
+      ]
+    },
+    popups: {
+      title: "Popups",
+      guidelines: [
+        "Use PopupCard with PopupHeader/PopupContent/PopupFooter for structured popups",
+        "Set `closeOnClick={false}` if popup should persist until explicitly closed",
+        "Use `autoPan={true}` (default) to ensure popup is visible when opened",
+        "Popup content can be any React/Svelte component",
+        "Consider `maxWidth` prop for content-heavy popups"
+      ]
+    },
+    markers: {
+      title: "Markers",
+      guidelines: [
+        "DOM-based Marker components use maplibregl.Marker which renders in the DOM",
+        "DOM markers are susceptible to CSS framework interference (e.g., Tailwind) that can cause visual sliding during pan/rotate",
+        "For production use with many markers or when CSS conflicts occur, prefer SymbolLayer which renders on the GPU canvas",
+        "SymbolLayer is immune to CSS interference and generally performs better at scale",
+        "Use Marker component only for simple cases or when you need custom HTML content that can't be achieved with icons",
+        "If using DOM markers, the component applies CSS protection but this may not fully prevent sliding in all CSS environments"
+      ]
+    },
+    dynamicData: {
+      title: "Dynamic Data Loading",
+      description: "Patterns for loading and updating map data dynamically (async fetching, user interactions, etc.)",
+      guidelines: [
+        "For dynamic marker-like points, use Source + CircleLayer/SymbolLayer instead of individual Marker components",
+        "When Source data prop changes, the component automatically calls source.setData() to update layers efficiently",
+        "Convert your data array to GeoJSON FeatureCollection format using useMemo/derived to avoid unnecessary re-renders",
+        "Layers automatically re-render when their source data changes - no need to recreate layers",
+        "Use generateId prop on Source to enable feature state (hover effects, selection)",
+        "For popups with SymbolLayer, use onClick handler to get feature coordinates and properties",
+        "This approach is more performant than DOM markers: single GPU draw call vs O(n) DOM operations",
+        "DOM Markers also support dynamic loading - they appear immediately when added after map initialization"
+      ],
+      recommendedPattern: {
+        name: "Dynamic SymbolLayer with Popup",
+        description: "Recommended pattern for dynamic points with popups - GPU-based, efficient, and immune to CSS conflicts",
+        react: `const [points, setPoints] = useState([]);
+
+const geojson = useMemo(() => ({
+  type: 'FeatureCollection',
+  features: points.map(p => ({
+    type: 'Feature',
+    properties: { name: p.name, id: p.id },
+    geometry: { type: 'Point', coordinates: p.coordinates }
+  }))
+}), [points]);
+
+const [selected, setSelected] = useState(null);
+
+return (
+  <Map title="Dynamic Points">
+    <Source id="points" type="geojson" data={geojson} generateId>
+      <CircleLayer
+        id="circles"
+        source="points"
+        circleRadius={10}
+        circleColor="#3ba4a7"
+        onClick={(e) => setSelected({ ...e.feature.properties, coordinates: e.lngLat })}
+        onHover={() => {}}
+      />
+      <SymbolLayer
+        id="labels"
+        source="points"
+        textField={['get', 'name']}
+        textOffset={[0, 1.5]}
+      />
+    </Source>
+    {selected && (
+      <Popup coordinates={selected.coordinates} onClose={() => setSelected(null)} closeButton>
+        <PopupCard>
+          <PopupHeader title={selected.name} />
+        </PopupCard>
+      </Popup>
+    )}
+  </Map>
+);`,
+        svelte: `<script>
+  let points = $state([]);
+  let selected = $state(null);
+
+  const geojson = $derived({
+    type: 'FeatureCollection',
+    features: points.map(p => ({
+      type: 'Feature',
+      properties: { name: p.name, id: p.id },
+      geometry: { type: 'Point', coordinates: p.coordinates }
+    }))
+  });
+</script>
+
+<Map title="Dynamic Points">
+  <Source id="points" type="geojson" data={geojson} generateId>
+    <CircleLayer
+      id="circles"
+      source="points"
+      circleRadius={10}
+      circleColor="#3ba4a7"
+      onClick={(e) => selected = { ...e.feature.properties, coordinates: e.lngLat }}
+      onHover={() => {}}
+    />
+    <SymbolLayer id="labels" source="points" textField={['get', 'name']} textOffset={[0, 1.5]} />
+  </Source>
+  {#if selected}
+    <Popup coordinates={selected.coordinates} onClose={() => selected = null} closeButton>
+      <PopupCard><PopupHeader title={selected.name} /></PopupCard>
+    </Popup>
+  {/if}
+</Map>`
+      },
+      comparisonTable: {
+        description: "Comparison of dynamic data approaches",
+        approaches: [
+          {
+            name: "Source + SymbolLayer (Recommended)",
+            updateMechanism: "source.setData() on existing source",
+            performance: "Single GPU draw call",
+            cssImmunity: "Yes - rendered on canvas",
+            useCase: "Most marker-like use cases, especially with many points"
+          },
+          {
+            name: "DOM Markers",
+            updateMechanism: "Create/destroy marker instances",
+            performance: "O(n) DOM operations",
+            cssImmunity: "No - CSS protection applied but not guaranteed",
+            useCase: "Custom HTML content that can't be achieved with icons"
+          }
+        ]
+      }
+    },
+    mapboxMigration: {
+      title: "Migrating from Mapbox GL",
+      differences: [
+        "No access token required (MapLibre is open source)",
+        "Use `theme='light'` or `theme='dark'` instead of Mapbox style URLs",
+        "Replace `mapboxgl.accessToken = 'pk...'` with nothing",
+        "Replace `mapbox://styles/*` with theme prop or custom style URL",
+        "Replace imperative `map.addLayer()` with declarative `<CircleLayer />` components",
+        "Replace `map.on('click', layer, fn)` with `<Layer onClick={fn} />`"
+      ],
+      exampleMigration: `// Before (Mapbox)
+import mapboxgl from 'mapbox-gl';
+mapboxgl.accessToken = 'pk.xxx';
+const map = new mapboxgl.Map({ container, style: 'mapbox://styles/...' });
+map.on('load', () => {
+  map.addSource('data', { type: 'geojson', data });
+  map.addLayer({ id: 'points', type: 'circle', source: 'data' });
+});
+
+// After (Classic Theme)
+import { Map, Source, CircleLayer } from '@classic-homes/maps-react';
+
+<Map title="Properties" center={[-122.4, 37.8]} zoom={12}>
+  <Source id="data" type="geojson" data={geojson}>
+    <CircleLayer id="points" source="data" circleRadius={8} onClick={handleClick} />
+  </Source>
+</Map>`
+    }
+  },
+  themeTypes: {
+    description: "Theme-related TypeScript types",
+    types: [
+      {
+        name: "MapTheme",
+        description: "Complete theme configuration for maps",
+        properties: [
+          { name: "name", type: "string", required: true, description: "Theme identifier ('classic-light' or 'classic-dark')" },
+          { name: "colors", type: "MapThemeColors", required: true, description: "UI and base colors" },
+          { name: "dataColors", type: "MapDataColors", required: true, description: "Data visualization colors" },
+          { name: "typography", type: "{ fontFamily: string; sizes: Record<string, number> }", required: true, description: "Typography settings" }
+        ]
+      },
+      {
+        name: "MapThemeColors",
+        description: "Theme colors for map UI elements",
+        properties: [
+          { name: "background", type: "string", required: true, description: "Map background color" },
+          { name: "text", type: "string", required: true, description: "Primary text color" },
+          { name: "textMuted", type: "string", required: true, description: "Muted text color" },
+          { name: "border", type: "string", required: true, description: "Border color" },
+          { name: "water", type: "string", required: true, description: "Water feature color" },
+          { name: "land", type: "string", required: true, description: "Land/terrain color" },
+          { name: "road", type: "string", required: true, description: "Road color" },
+          { name: "building", type: "string", required: true, description: "Building color" },
+          { name: "park", type: "string", required: true, description: "Park/green space color" }
+        ]
+      },
+      {
+        name: "MapDataColors",
+        description: "Colors for data visualization layers (5 colors for series)",
+        properties: [
+          { name: "primary", type: "string", required: true, description: "Primary data color (chart-1)" },
+          { name: "secondary", type: "string", required: true, description: "Secondary data color (chart-2)" },
+          { name: "tertiary", type: "string", required: true, description: "Tertiary data color (chart-3)" },
+          { name: "quaternary", type: "string", required: true, description: "Quaternary data color (chart-4)" },
+          { name: "quinary", type: "string", required: true, description: "Quinary data color (chart-5)" },
+          { name: "highlight", type: "string", required: true, description: "Highlight/hover color" },
+          { name: "selection", type: "string", required: true, description: "Selection color" }
+        ]
+      },
+      {
+        name: "MapStyleSpec",
+        description: "MapLibre style specification (StyleSpecification from maplibre-gl)"
+      },
+      {
+        name: "ColorExpression",
+        description: "MapLibre expression that evaluates to a color (string | Expression)"
+      },
+      {
+        name: "NumberExpression",
+        description: "MapLibre expression that evaluates to a number (number | Expression)"
+      }
+    ]
+  }
+};
+
+// src/resources/maps.ts
+var catalog5 = maps_catalog_default;
+function registerMapsResources(server) {
+  server.resource("Maps Core Package", "maps://all", async (uri) => ({
+    contents: [
+      {
+        uri: uri.href,
+        mimeType: "application/json",
+        text: JSON.stringify(catalog5, null, 2)
+      }
+    ]
+  }));
+  server.resource("Maps Theme", "maps://theme", async (uri) => ({
+    contents: [
+      {
+        uri: uri.href,
+        mimeType: "application/json",
+        text: JSON.stringify(
+          {
+            importPath: catalog5.subpackages.theme.importPath,
+            description: catalog5.subpackages.theme.description,
+            functions: catalog5.subpackages.main.modules?.theme.functions
+          },
+          null,
+          2
+        )
+      }
+    ]
+  }));
+  server.resource("Maps Types", "maps://types", async (uri) => ({
+    contents: [
+      {
+        uri: uri.href,
+        mimeType: "application/json",
+        text: JSON.stringify(
+          {
+            importPath: catalog5.subpackages.types.importPath,
+            description: "TypeScript types exported from @classic-homes/maps-core",
+            props: catalog5.types.props,
+            data: catalog5.types.data,
+            events: catalog5.types.events
+          },
+          null,
+          2
+        )
+      }
+    ]
+  }));
+  server.resource("Maps Utilities", "maps://utils", async (uri) => ({
+    contents: [
+      {
+        uri: uri.href,
+        mimeType: "application/json",
+        text: JSON.stringify(
+          {
+            importPath: catalog5.subpackages.main.importPath,
+            description: "Utility functions for formatting, accessibility, and styling",
+            format: catalog5.subpackages.main.modules?.format,
+            accessibility: catalog5.subpackages.main.modules?.accessibility,
+            styles: catalog5.subpackages.main.modules?.styles
+          },
+          null,
+          2
+        )
+      }
+    ]
+  }));
+  server.resource("Maps Components", "maps://components", async (uri) => ({
+    contents: [
+      {
+        uri: uri.href,
+        mimeType: "application/json",
+        text: JSON.stringify(catalog5.components, null, 2)
+      }
+    ]
+  }));
+  server.resource("Maps Quick Reference", "maps://quick-reference", async (uri) => ({
+    contents: [
+      {
+        uri: uri.href,
+        mimeType: "text/markdown",
+        text: `# Maps Core Quick Reference
+
+## Installation
+
+\`\`\`bash
+${catalog5.quickReference.installation}
+\`\`\`
+
+## Basic Usage
+
+\`\`\`typescript
+${catalog5.quickReference.basicUsage}
+\`\`\`
+
+## Peer Dependency
+
+\`${catalog5.quickReference.peerDependency}\`
+
+## Optional Peer Dependencies (for Deck.gl)
+
+\`${catalog5.quickReference.optionalPeerDependencies}\`
+
+## Available Components
+
+**React:** \`@classic-homes/maps-react\`
+- ${catalog5.components.react.components.join(", ")}
+
+**Svelte:** \`@classic-homes/maps-svelte\`
+- ${catalog5.components.svelte.components.join(", ")}
+
+## Theme Exports
+
+- \`generateLightTheme()\` - Generate light theme from tokens
+- \`generateDarkTheme()\` - Generate dark theme from tokens
+- \`lightTheme\` - Pre-generated light theme
+- \`darkTheme\` - Pre-generated dark theme
+- \`lightBasicStyle\` - Pre-generated light MapLibre style
+- \`darkBasicStyle\` - Pre-generated dark MapLibre style
+- \`THEME_LIGHT\` - Constant: 'classic-light'
+- \`THEME_DARK\` - Constant: 'classic-dark'
+
+## Layer Types
+
+- **FillLayer** - Polygon fills (choropleth, areas)
+- **LineLayer** - Lines (routes, borders)
+- **CircleLayer** - Point circles
+- **SymbolLayer** - Icons and text labels
+- **FillExtrusionLayer** - 3D building extrusions
+- **HeatmapLayer** - Point density visualization
+- **DeckOverlay** - Deck.gl integration for advanced WebGL
+
+## Formatting Utilities
+
+- \`formatCoordinates(coordinates, precision?, format?)\` - Format coordinates (decimal, DMS, or DD)
+- \`formatDistance(meters, unit?)\` - Format distance (metric or imperial)
+- \`formatArea(sqMeters, unit?)\` - Format area (metric or imperial)
+- \`formatBounds(bounds)\` - Format bounding box
+
+## Accessibility Utilities
+
+- \`generateMapDescription(title, options?)\` - Accessible map description
+- \`generateFeatureCollectionDescription(collection, name?)\` - Describe features
+- \`KEYBOARD_CONTROLS\` - Keyboard shortcut descriptions
+
+## Styling Utilities
+
+- \`createHoverExpression(baseColor, hoverColor)\` - Hover state expression
+- \`createSelectionExpression(baseColor, selectedColor)\` - Selection expression
+- \`getHighlightStyle(theme)\` - Highlight style properties
+- \`getSelectionStyle(theme)\` - Selection style properties
+
+## React Hooks
+
+- \`useMap()\` - Access map instance and state from context
+- \`useMapInstance()\` - Get map instance when loaded (returns null otherwise)
+- \`useMapTheme(theme?)\` - Get resolved theme, map theme object, and style
+- \`useReducedMotion()\` - Detect user's motion preference
+- \`useLayer(options)\` - Add custom layers with automatic lifecycle
+
+## CSS Import Order
+
+\`\`\`css
+@import '@classic-homes/theme-styles';
+@import 'maplibre-gl/dist/maplibre-gl.css';
+@import '@classic-homes/maps-core/styles/controls.css';
+@import '@classic-homes/maps-core/styles/popup.css';
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+\`\`\`
+`
+      }
+    ]
+  }));
+  server.resource("Maps Props Types", "maps://props", async (uri) => ({
+    contents: [
+      {
+        uri: uri.href,
+        mimeType: "application/json",
+        text: JSON.stringify(catalog5.types.props, null, 2)
+      }
+    ]
+  }));
+  server.resource("Maps Data Types", "maps://data", async (uri) => ({
+    contents: [
+      {
+        uri: uri.href,
+        mimeType: "application/json",
+        text: JSON.stringify(catalog5.types.data, null, 2)
+      }
+    ]
+  }));
+  server.resource("Maps Event Types", "maps://events", async (uri) => ({
+    contents: [
+      {
+        uri: uri.href,
+        mimeType: "application/json",
+        text: JSON.stringify(catalog5.types.events, null, 2)
+      }
+    ]
+  }));
+  server.resource("Maps React Hooks", "maps://hooks", async (uri) => ({
+    contents: [
+      {
+        uri: uri.href,
+        mimeType: "application/json",
+        text: JSON.stringify(
+          {
+            package: catalog5.components.react.package,
+            hooks: catalog5.components.react.hooks,
+            context: catalog5.components.react.context
+          },
+          null,
+          2
+        )
+      }
+    ]
+  }));
+  server.resource("Maps Best Practices", "maps://best-practices", async (uri) => ({
+    contents: [
+      {
+        uri: uri.href,
+        mimeType: "application/json",
+        text: JSON.stringify(catalog5.bestPractices, null, 2)
+      }
+    ]
+  }));
+  server.resource("Maps Theme Types", "maps://theme-types", async (uri) => ({
+    contents: [
+      {
+        uri: uri.href,
+        mimeType: "application/json",
+        text: JSON.stringify(catalog5.themeTypes, null, 2)
+      }
+    ]
+  }));
+  server.resource("Maps Migration Guide", "maps://migration", async (uri) => ({
+    contents: [
+      {
+        uri: uri.href,
+        mimeType: "text/markdown",
+        text: `# Migrating from Mapbox GL to Classic Theme Maps
+
+## Key Differences
+
+${catalog5.bestPractices?.mapboxMigration.differences?.map((d) => `- ${d}`).join("\n")}
+
+## Example Migration
+
+\`\`\`typescript
+${catalog5.bestPractices?.mapboxMigration.exampleMigration}
+\`\`\`
+
+## CSS Setup
+
+\`\`\`css
+${catalog5.quickReference.cssImportOrder}
+\`\`\`
+
+## Tailwind Configuration
+
+\`\`\`javascript
+${catalog5.quickReference.tailwindConfig}
+\`\`\`
+`
+      }
+    ]
+  }));
+}
+
 // src/resources/index.ts
 function registerResources(server) {
   registerComponentResources(server);
@@ -17376,11 +19387,12 @@ function registerResources(server) {
   registerNotificationsResources(server);
   registerDocsResources(server);
   registerChartsResources(server);
+  registerMapsResources(server);
 }
 
 // src/tools/searchComponents.ts
 import { z } from "zod";
-var catalog5 = component_catalog_default;
+var catalog6 = component_catalog_default;
 var SearchComponentsSchema = z.object({
   query: z.string().describe("Search query (component name, description, or functionality)"),
   category: z.enum([
@@ -17406,7 +19418,7 @@ function registerSearchComponentsTool(server) {
       const queryLower = query.toLowerCase().trim();
       const isListAll = queryLower === "*" || queryLower === "all" || queryLower === "" || queryLower === "list" || queryLower === "list all";
       const queryWords = queryLower.split(/\s+/).filter((word) => word.length > 0);
-      const results = catalog5.components.filter((component) => {
+      const results = catalog6.components.filter((component) => {
         if (category && component.category !== category) {
           return false;
         }
@@ -17473,7 +19485,7 @@ function registerSearchComponentsTool(server) {
 
 // src/tools/getComponentProps.ts
 import { z as z2 } from "zod";
-var catalog6 = component_catalog_default;
+var catalog7 = component_catalog_default;
 var GetComponentPropsSchema = z2.object({
   componentName: z2.string().describe('Name of the component (e.g., "Button", "DashboardLayout")'),
   includeExamples: z2.boolean().default(true).describe("Whether to include usage examples")
@@ -17485,11 +19497,11 @@ function registerGetComponentPropsTool(server) {
     GetComponentPropsSchema.shape,
     async (params) => {
       const { componentName, includeExamples } = GetComponentPropsSchema.parse(params);
-      const component = catalog6.components.find(
+      const component = catalog7.components.find(
         (c) => c.name.toLowerCase() === componentName.toLowerCase()
       );
       if (!component) {
-        const suggestions = catalog6.components.filter((c) => c.name.toLowerCase().includes(componentName.toLowerCase().slice(0, 3))).slice(0, 5).map((c) => c.name);
+        const suggestions = catalog7.components.filter((c) => c.name.toLowerCase().includes(componentName.toLowerCase().slice(0, 3))).slice(0, 5).map((c) => c.name);
         return {
           content: [
             {
@@ -17634,7 +19646,7 @@ function registerSuggestPatternTool(server) {
 
 // src/tools/validateUsage.ts
 import { z as z4 } from "zod";
-var catalog7 = component_catalog_default;
+var catalog8 = component_catalog_default;
 var ValidateUsageSchema = z4.object({
   componentName: z4.string().describe("Name of the component being used"),
   props: z4.record(z4.unknown()).describe("Props being passed to the component"),
@@ -17647,7 +19659,7 @@ function registerValidateUsageTool(server) {
     ValidateUsageSchema.shape,
     async (params) => {
       const { componentName, props, context } = ValidateUsageSchema.parse(params);
-      const component = catalog7.components.find(
+      const component = catalog8.components.find(
         (c) => c.name.toLowerCase() === componentName.toLowerCase()
       );
       if (!component) {
@@ -17960,7 +19972,7 @@ Example for ${pageType}Layout:
 
 // src/prompts/componentUsage.ts
 import { z as z7 } from "zod";
-var catalog8 = component_catalog_default;
+var catalog9 = component_catalog_default;
 var ComponentUsageSchema = z7.object({
   componentName: z7.string().describe("Name of the component (e.g., Button, Card, Select)"),
   variant: z7.string().optional().describe("Desired variant (optional)"),
@@ -17976,7 +19988,7 @@ function registerComponentUsagePrompt(server) {
       const componentName = parsed.componentName || "Button";
       const variant = parsed.variant || "";
       const useCase = parsed.useCase || "";
-      const component = catalog8.components.find(
+      const component = catalog9.components.find(
         (c) => c.name.toLowerCase() === componentName.toLowerCase()
       );
       let componentInfo = "";
@@ -17998,7 +20010,7 @@ ${component.examples.map((e) => `### ${e.title}
 ${e.code}
 \`\`\``).join("\n\n")}`;
       } else {
-        componentInfo = `Component "${componentName}" not found in catalog. Available components: ${catalog8.components.map((c) => c.name).join(", ")}`;
+        componentInfo = `Component "${componentName}" not found in catalog. Available components: ${catalog9.components.map((c) => c.name).join(", ")}`;
       }
       return {
         messages: [