用途：为 FixMyBerlin / FMC 项目中的 react-map-gl（MapLibre）使用提供统一约定，适用于新增或修改 Map、Source、Layer、控件与标记，点击/悬停/要素检查，视口与 URL 同步，以及调试“地图半加载”、样式图片缺失或点击目标错误等问题。
主要能力与规则： 导入与样式：从 react-map-gl/maplibre 导入（不是单独 react-map-gl），并始终导入 maplibre-gl/dist/maplibre-gl.css。 声明式图层：仅用 JSX 中的 <Source> + <Layer>，应用数据绝不使用 map.addSource / map.addLayer（及 remove*）；显示/隐藏用 layout.visibility 或条件渲染。图层采用平级兄弟结构，每个 source id 对应一个 <Source>，其后为同级 <Layer>。 地图事件：相机、指针、加载和切片生命周期使用 <Map> 回调属性，不用 useEffect + map.on(…)。 地图访问：应用地图 UI 包在 <MapProvider> 中，用 useMap() 并按 <Map id="…"> 取用，不通过 ref 传 <Map>。 就绪守卫：getStyle、queryRenderedFeatures、setFeatureState 等需用 useMapLoaded()（在 onLoad 中设置）保护。 点击拾取：把图层 id 放入 interactiveLayerIds，在处理器中读取 event.features，不要为主要的点击拾取调用 queryRenderedFeatures（除非同步 URL 要素）。 要素高亮：检验器/表单状态以 React 为准，地图着色用 setFeatureState（paint）或 React 过滤图层，应用新状态前先清除旧状态。 归属控件：<Map> 上 attributionControl={false}，并添加 <AttributionControl compact> 子元素。 视口与 URL：按缩放级别对经纬度取整后序列化 zoom/lat/lng，在 onMoveEnd 中以 history: 'replace' 写入。视口状态优先用从 URL 初始化的非受控 initialViewState，除非需要程序化相机控制，否则不要把完整 viewState 镜像到 React state。 调试暴露：在 onLoad 中调用 exposeMainMapForDebugging(event.target)（仅开发与 Playwright），代理/测试读取 window.__mainMap。 参考文档：declarative-source-layer.md、map-event-handlers.md、map-provider-wrapper.md、interactive-layer-ids.md、map-loaded-hook.md、map-debug-exposure.md、feature-state.md、flat-source-layer.md、layer-visibility-vs-unmount.md、map-props-attribution-locale.md、cursor-handling.md、initial-view-state.md、map-url-state.md、map-images-missing.md、map-images-proactive.md。可配合 tanstack-router-conventions、nuqs、zustand-state-management、playwright-skill 使用。
快速导入： import 'maplibre-gl/dist/maplibre-gl.css' import { MapProvider, Map, Source, Layer, useMap } from 'react-map-gl/maplibre'
限制：资料未提供版本要求、安装命令、收费或价格信息。