@movk/maplibre 1.0.0 → 1.2.0

package/README.en.md

@@ -130,8 +130,8 @@ All components are prefixed with `Maplibre` by default (configurable). Grouped b
 | Core | `MaplibreMap` `MaplibreSource` `MaplibreLayer` `MaplibreLayerGroup` `MaplibreCustomLayer` `MaplibreMarker` `MaplibreLottieMarker` `MaplibrePopup` `MaplibreTooltip` |
 | Layers | `MaplibreBuildingLayer` `MaplibreClusterLayer` `MaplibreImageLayer` `MaplibreRasterLayer` `MaplibreVideoLayer` |
 | Effects | `MaplibreRadar` `MaplibreDiffusionCircle` `MaplibreGlowCircle` `MaplibreWaveCircle` `MaplibreGradientBuilding` `MaplibreTextureBuilding` `MaplibreWindowBuilding` `MaplibreFlowBuilding` `MaplibreMigration` `MaplibreTrail` `MaplibreAnimatedImage` `MaplibreSpriteImage` |
-| Environment | `MaplibreSky` `MaplibreTerrain` `MaplibreTemperature` |
-| Controls | `MaplibreNavigationControl` `MaplibreGeolocateControl` `MaplibreFullscreenControl` `MaplibreScaleControl` `MaplibreAttributionControl` |
+| Environment | `MaplibreSky` `MaplibreProjection` `MaplibreTerrain` `MaplibreTemperature` |
+| Controls | `MaplibreNavigationControl` `MaplibreGeolocateControl` `MaplibreFullscreenControl` `MaplibreGlobeControl` `MaplibreScaleControl` `MaplibreAttributionControl` |
 | Extensions | `MaplibreDrawControl` `MaplibreTiandituLayer` `MaplibreWmsLayer` `MaplibreWmtsLayer` |
 | Buffers | `MaplibreBufferCircle` `MaplibreBufferEllipse` `MaplibreBufferLine` `MaplibreBufferPolygon` `MaplibreBufferSector` |
 

package/README.md

@@ -129,8 +129,8 @@ const zoom = ref(9)
 | 核心 | `MaplibreMap` `MaplibreSource` `MaplibreLayer` `MaplibreLayerGroup` `MaplibreCustomLayer` `MaplibreMarker` `MaplibreLottieMarker` `MaplibrePopup` `MaplibreTooltip` |
 | 图层 | `MaplibreBuildingLayer` `MaplibreClusterLayer` `MaplibreImageLayer` `MaplibreRasterLayer` `MaplibreVideoLayer` |
 | 效果 | `MaplibreRadar` `MaplibreDiffusionCircle` `MaplibreGlowCircle` `MaplibreWaveCircle` `MaplibreGradientBuilding` `MaplibreTextureBuilding` `MaplibreWindowBuilding` `MaplibreFlowBuilding` `MaplibreMigration` `MaplibreTrail` `MaplibreAnimatedImage` `MaplibreSpriteImage` |
-| 环境 | `MaplibreSky` `MaplibreTerrain` `MaplibreTemperature` |
-| 控件 | `MaplibreNavigationControl` `MaplibreGeolocateControl` `MaplibreFullscreenControl` `MaplibreScaleControl` `MaplibreAttributionControl` |
+| 环境 | `MaplibreSky` `MaplibreProjection` `MaplibreTerrain` `MaplibreTemperature` |
+| 控件 | `MaplibreNavigationControl` `MaplibreGeolocateControl` `MaplibreFullscreenControl` `MaplibreGlobeControl` `MaplibreScaleControl` `MaplibreAttributionControl` |
 | 扩展 | `MaplibreDrawControl` `MaplibreTiandituLayer` `MaplibreWmsLayer` `MaplibreWmtsLayer` |
 | 缓冲 | `MaplibreBufferCircle` `MaplibreBufferEllipse` `MaplibreBufferLine` `MaplibreBufferPolygon` `MaplibreBufferSector` |
 

package/dist/module.d.mts

@@ -1,4 +1,4 @@
-import * as _nuxt_schema from '@nuxt/schema';
+import { NuxtModule } from '@nuxt/schema';
 export * from '../dist/runtime/types/index.js';
 
 interface ModuleOptions {
@@ -13,8 +13,17 @@ interface ModuleOptions {
      * @defaultValue 'Maplibre'
      */
     prefix?: string;
+    /** 按需注册数据协议（需安装对应可选依赖）；开启后在客户端插件中注册，未开启时不打包相关依赖 */
+    protocols?: {
+        /** 注册 `pmtiles://` 协议，依赖 pmtiles */
+        pmtiles?: boolean;
+        /** 注册 `cog://` 协议，依赖 @geomatico/maplibre-cog-protocol */
+        cog?: boolean;
+        /** 注册 `zzts://` 协议（ZZTS 二维动态切片服务），无额外依赖；需自定义请求时改为自行调用 `registerZztsProtocol` */
+        zzts?: boolean;
+    };
 }
-declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+declare const module$1: NuxtModule<ModuleOptions, ModuleOptions, false>;
 
-export { _default as default };
+export { module$1 as default };
 export type { ModuleOptions };

package/dist/module.d.ts

@@ -1,4 +1,4 @@
-import * as _nuxt_schema from '@nuxt/schema';
+import { NuxtModule } from '@nuxt/schema';
 export * from '../dist/runtime/types/index.js';
 
 interface ModuleOptions {
@@ -13,8 +13,17 @@ interface ModuleOptions {
      * @defaultValue 'Maplibre'
      */
     prefix?: string;
+    /** 按需注册数据协议（需安装对应可选依赖）；开启后在客户端插件中注册，未开启时不打包相关依赖 */
+    protocols?: {
+        /** 注册 `pmtiles://` 协议，依赖 pmtiles */
+        pmtiles?: boolean;
+        /** 注册 `cog://` 协议，依赖 @geomatico/maplibre-cog-protocol */
+        cog?: boolean;
+        /** 注册 `zzts://` 协议（ZZTS 二维动态切片服务），无额外依赖；需自定义请求时改为自行调用 `registerZztsProtocol` */
+        zzts?: boolean;
+    };
 }
-declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+declare const module$1: NuxtModule<ModuleOptions, ModuleOptions, false>;
 
-export { _default as default };
+export { module$1 as default };
 export type { ModuleOptions };

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "@movk/maplibre",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "configKey": "maplibre",
   "compatibility": {
     "nuxt": ">=4.0.0"

package/dist/module.mjs

@@ -1,10 +1,11 @@
 import { createRequire } from 'node:module';
-import { defineNuxtModule, createResolver, addComponentsDir, addImportsDir, addImports, addPlugin, addPluginTemplate, extendViteConfig } from '@nuxt/kit';
+import { defineNuxtModule, createResolver, addComponentsDir, addImportsDir, addPlugin, addPluginTemplate, extendViteConfig } from '@nuxt/kit';
 import { defu } from 'defu';
 
 const name = "@movk/maplibre";
-const version = "1.0.0";
+const version = "1.2.0";
 
+const OPTIONAL_DEPS = ["lottie-web", "pmtiles", "@geomatico/maplibre-cog-protocol", "maplibre-contour"];
 const module$1 = defineNuxtModule({
   meta: {
     name,
@@ -31,10 +32,6 @@ const module$1 = defineNuxtModule({
       pathPrefix: false
     });
     addImportsDir(resolve("./runtime/composables"));
-    addImports([
-      { name: "movkDrawModes", from: resolve("./runtime/draw-modes") },
-      { name: "drawThemeStyles", from: resolve("./runtime/utils/draw-theme") }
-    ]);
     addPlugin({ src: resolve("./runtime/plugins/config") });
     addPluginTemplate({
       filename: "movk-maplibre-worker.client.mjs",
@@ -46,15 +43,33 @@ const module$1 = defineNuxtModule({
         `export default defineNuxtPlugin(() => { setMaplibreConfig({ workerUrl }) })`
       ].join("\n")
     });
+    const protocols = [
+      options.protocols?.pmtiles && { path: "./runtime/utils/pmtiles", register: "registerPmtilesProtocol" },
+      options.protocols?.cog && { path: "./runtime/utils/cog", register: "registerCogProtocol" },
+      options.protocols?.zzts && { path: "./runtime/utils/zzts", register: "registerZztsProtocol" }
+    ].filter((item) => !!item);
+    if (protocols.length) {
+      addPluginTemplate({
+        filename: "movk-maplibre-protocols.client.mjs",
+        mode: "client",
+        getContents: () => [
+          `import { defineNuxtPlugin } from '#app'`,
+          ...protocols.map(({ path, register }) => `import { ${register} } from ${JSON.stringify(resolve(path))}`),
+          `export default defineNuxtPlugin(() => { ${protocols.map(({ register }) => `${register}()`).join("; ")} })`
+        ].join("\n")
+      });
+    }
     extendViteConfig((config) => {
       config.optimizeDeps ||= {};
       const include = config.optimizeDeps.include ||= [];
       const require = createRequire(import.meta.url);
-      if (include.includes("lottie-web")) return;
-      try {
-        require.resolve("lottie-web", { paths: [nuxt.options.rootDir] });
-        include.push("lottie-web");
-      } catch {
+      for (const dep of OPTIONAL_DEPS) {
+        if (include.includes(dep)) continue;
+        try {
+          require.resolve(dep, { paths: [nuxt.options.rootDir] });
+          include.push(dep);
+        } catch {
+        }
       }
     });
   }

package/dist/runtime/components/CustomLayer.d.vue.ts

@@ -2,7 +2,7 @@ import type { CustomLayerInterface } from 'maplibre-gl';
 /** CustomLayerInterface 逃生舱：托管自定义 WebGL 图层的挂载/卸载与样式重载重建。 */
 type __VLS_Props = {
     /**
-     * 自定义图层实现（含 id/type/render）
+     * 自定义图层实现（含 id/type/render）；按引用比较，替换对象时移除旧图层并添加新图层
      * @see https://maplibre.org/maplibre-gl-js/docs/API/interfaces/CustomLayerInterface/
      */
     layer: CustomLayerInterface;

package/dist/runtime/components/CustomLayer.vue

@@ -1,15 +1,29 @@
 <script setup>
-import { onUnmounted } from "vue";
+import { onUnmounted, toRaw, watch } from "vue";
 import { useMap } from "../composables/useMap";
 const props = defineProps({
   layer: { type: Object, required: true },
   beforeId: { type: String, required: false }
 });
 const ctx = useMap();
-const stopReady = ctx.onReady((map) => {
+function resolveBeforeId(map) {
+  return props.beforeId && map.getLayer(props.beforeId) ? props.beforeId : void 0;
+}
+function addLayer(map) {
   if (map.getLayer(props.layer.id)) return;
-  const before = props.beforeId && map.getLayer(props.beforeId) ? props.beforeId : void 0;
-  map.addLayer(props.layer, before);
+  map.addLayer(toRaw(props.layer), resolveBeforeId(map));
+}
+const stopReady = ctx.onReady(addLayer);
+watch(() => props.layer, (_next, prev) => {
+  const map = ctx.map.value;
+  if (!map?.getLayer(prev.id)) return;
+  map.removeLayer(prev.id);
+  addLayer(map);
+});
+watch(() => props.beforeId, () => {
+  const map = ctx.map.value;
+  if (!map?.getLayer(props.layer.id)) return;
+  map.moveLayer(props.layer.id, resolveBeforeId(map));
 });
 onUnmounted(() => {
   stopReady();

package/dist/runtime/components/CustomLayer.vue.d.ts

@@ -2,7 +2,7 @@ import type { CustomLayerInterface } from 'maplibre-gl';
 /** CustomLayerInterface 逃生舱：托管自定义 WebGL 图层的挂载/卸载与样式重载重建。 */
 type __VLS_Props = {
     /**
-     * 自定义图层实现（含 id/type/render）
+     * 自定义图层实现（含 id/type/render）；按引用比较，替换对象时移除旧图层并添加新图层
      * @see https://maplibre.org/maplibre-gl-js/docs/API/interfaces/CustomLayerInterface/
      */
     layer: CustomLayerInterface;

package/dist/runtime/components/Layer.d.vue.ts

@@ -1,16 +1,16 @@
 import type { FilterSpecification, LayerSpecification, SourceSpecification } from '@maplibre/maplibre-gl-style-spec';
 type PropBag = Record<string, unknown>;
 type __VLS_Props = {
-    /** 图层 id，全局唯一 */
+    /** 图层 id，全局唯一；变更需配合 `:key` 重建 */
     layerId: string;
     /**
-     * 图层类型，决定渲染方式与可用的 paint / layout 属性
+     * 图层类型，决定渲染方式与可用的 paint / layout 属性；变更需配合 `:key` 重建
      * @see https://maplibre.org/maplibre-style-spec/layers/
      */
     type: LayerSpecification['type'];
-    /** source id 字符串引用，或内联 source 对象（自动创建匿名源并随图层卸载） */
+    /** source id 字符串引用，或内联 source 对象（自动创建匿名源并随图层卸载，内容变化时增量更新）；二者之间切换需配合 `:key` 重建 */
     source?: string | SourceSpecification;
-    /** 矢量瓦片源内的子图层名（source-layer），消费矢量源时必填 */
+    /** 矢量瓦片源内的子图层名（source-layer），消费矢量源时必填；变更需配合 `:key` 重建 */
     sourceLayer?: string;
     /**
      * 绘制样式属性，响应式变更经 setPaintProperty 增量下发

package/dist/runtime/components/Layer.vue

@@ -1,10 +1,12 @@
 <script setup>
-import { inject, onUnmounted, watch } from "vue";
+import { computed, inject, onUnmounted, watch } from "vue";
 import { omitUndefined } from "@movk/core";
 import { useMap } from "../composables/useMap";
 import { LayerGroupKey } from "../domains/map/layer-group";
 import { applyLayerProps } from "../utils/layer";
+import { opacityPropsFor, scaleOpacity } from "../utils/layer-opacity";
 import { bindMapEvents } from "../utils/events";
+import { updateSource } from "../utils/source";
 const props = defineProps({
   layerId: { type: String, required: true },
   type: { type: String, required: true },
@@ -21,6 +23,22 @@ const emit = defineEmits(["click", "dblclick", "mousedown", "mouseup", "mousemov
 const LAYER_EVENTS = ["click", "dblclick", "mousedown", "mouseup", "mousemove", "mouseenter", "mouseleave", "contextmenu"];
 const ctx = useMap();
 const group = inject(LayerGroupKey, null);
+const effectiveLayout = computed(() => {
+  if (!group) return props.layout;
+  const visibility = group.visible.value ? props.layout?.visibility ?? "visible" : "none";
+  return { ...props.layout, visibility };
+});
+const effectivePaint = computed(() => {
+  const factor = group?.opacity.value ?? 1;
+  if (factor === 1) return props.paint;
+  const scaled = Object.fromEntries(
+    opacityPropsFor(props.type).map((key) => [key, scaleOpacity(props.paint?.[key], factor)])
+  );
+  return { ...props.paint, ...scaled };
+});
+if (group) {
+  onUnmounted(group.registerLayer(() => ({ layerId: props.layerId, type: props.type, paint: props.paint })));
+}
 const inlineSourceId = `${props.layerId}__source`;
 const hasInlineSource = typeof props.source === "object";
 function resolveSourceId() {
@@ -32,8 +50,8 @@ function buildSpec() {
     id: props.layerId,
     type: props.type,
     source: resolveSourceId(),
-    paint: props.paint,
-    layout: props.layout,
+    paint: effectivePaint.value,
+    layout: effectiveLayout.value,
     filter: props.filter,
     minzoom: props.minzoom,
     maxzoom: props.maxzoom
@@ -41,17 +59,21 @@ function buildSpec() {
   if (props.sourceLayer) spec["source-layer"] = props.sourceLayer;
   return spec;
 }
+function resolveBeforeId(map) {
+  const anchor = props.beforeId ?? group?.beforeId.value;
+  return anchor && map.getLayer(anchor) ? anchor : void 0;
+}
+function currentUpdate() {
+  return { id: props.layerId, paint: effectivePaint.value, layout: effectiveLayout.value, filter: props.filter, minzoom: props.minzoom, maxzoom: props.maxzoom };
+}
+let prev = currentUpdate();
 function addLayer(map) {
   if (map.getLayer(props.layerId)) return;
   if (hasInlineSource && !map.getSource(inlineSourceId)) {
     map.addSource(inlineSourceId, props.source);
   }
-  const anchor = props.beforeId ?? group?.beforeId.value;
-  const before = anchor && map.getLayer(anchor) ? anchor : void 0;
-  map.addLayer(buildSpec(), before);
-  if (group && !group.visible.value) {
-    map.setLayoutProperty(props.layerId, "visibility", "none");
-  }
+  map.addLayer(buildSpec(), resolveBeforeId(map));
+  prev = currentUpdate();
 }
 let stopEvents;
 let onSourceData;
@@ -77,25 +99,28 @@ function bindLayerEvents(map) {
   stopEvents?.();
   stopEvents = bindMapEvents(map, LAYER_EVENTS, (type, event) => emit(type, event), props.layerId);
 }
-let prev = { id: props.layerId, paint: props.paint, layout: props.layout, filter: props.filter, minzoom: props.minzoom, maxzoom: props.maxzoom };
 watch(
-  () => [props.paint, props.layout, props.filter, props.minzoom, props.maxzoom],
+  () => [effectivePaint.value, effectiveLayout.value, props.filter, props.minzoom, props.maxzoom],
   () => {
     const map = ctx.map.value;
     if (!map?.getLayer(props.layerId)) return;
-    const next = { id: props.layerId, paint: props.paint, layout: props.layout, filter: props.filter, minzoom: props.minzoom, maxzoom: props.maxzoom };
+    const next = currentUpdate();
     applyLayerProps(map, next, prev);
     prev = next;
   },
   { deep: true }
 );
-if (group) {
-  watch(group.visible, (visible) => {
-    const map = ctx.map.value;
-    if (!map?.getLayer(props.layerId)) return;
-    map.setLayoutProperty(props.layerId, "visibility", visible ? "visible" : "none");
-  });
+if (hasInlineSource) {
+  watch(() => props.source, (next, prev2) => {
+    const source = ctx.map.value?.getSource(inlineSourceId);
+    if (source) updateSource(source, next, prev2);
+  }, { deep: true });
 }
+watch(() => props.beforeId ?? group?.beforeId.value, () => {
+  const map = ctx.map.value;
+  if (!map?.getLayer(props.layerId)) return;
+  map.moveLayer(props.layerId, resolveBeforeId(map));
+});
 onUnmounted(() => {
   stopReady();
   stopEvents?.();

package/dist/runtime/components/Layer.vue.d.ts

@@ -1,16 +1,16 @@
 import type { FilterSpecification, LayerSpecification, SourceSpecification } from '@maplibre/maplibre-gl-style-spec';
 type PropBag = Record<string, unknown>;
 type __VLS_Props = {
-    /** 图层 id，全局唯一 */
+    /** 图层 id，全局唯一；变更需配合 `:key` 重建 */
     layerId: string;
     /**
-     * 图层类型，决定渲染方式与可用的 paint / layout 属性
+     * 图层类型，决定渲染方式与可用的 paint / layout 属性；变更需配合 `:key` 重建
      * @see https://maplibre.org/maplibre-style-spec/layers/
      */
     type: LayerSpecification['type'];
-    /** source id 字符串引用，或内联 source 对象（自动创建匿名源并随图层卸载） */
+    /** source id 字符串引用，或内联 source 对象（自动创建匿名源并随图层卸载，内容变化时增量更新）；二者之间切换需配合 `:key` 重建 */
     source?: string | SourceSpecification;
-    /** 矢量瓦片源内的子图层名（source-layer），消费矢量源时必填 */
+    /** 矢量瓦片源内的子图层名（source-layer），消费矢量源时必填；变更需配合 `:key` 重建 */
     sourceLayer?: string;
     /**
      * 绘制样式属性，响应式变更经 setPaintProperty 增量下发

package/dist/runtime/components/LayerGroup.d.vue.ts

@@ -1,20 +1,33 @@
-/** 图层组：统一子图层的插入锚点与显隐（组开关优先于子图层自身 layout.visibility）。 */
+import type { LegendItem, StyleLayerPredicate } from '../types';
+/** 图层组：统一子图层的插入锚点、显隐与透明度；带 title 时进入图层树，供图层控件、图例与 useLayerTree 使用。 */
 type __VLS_Props = {
-    /** 组内图层缺省插入到该图层之前 */
+    /** 组内图层缺省插入到该图层之前；未设置时继承父组 */
     beforeId?: string;
-    /**
-     * 组级显隐
-     * @defaultValue true
-     */
-    visible?: boolean;
+    /** 组标题；设置后注册到图层树，出现在 MaplibreLayerControl、MaplibreLegend 与 useLayerTree 中 */
+    title?: string;
+    /** 图例项；省略时由子图层颜色推导 */
+    legend?: LegendItem[];
+    /** 认领底图样式自带的图层（按类型、source-layer 等匹配），与子图层一起受组的显隐与透明度控制 */
+    styleLayers?: StyleLayerPredicate;
 };
+type __VLS_ModelProps = {
+    /** 组级显隐（组开关优先于子图层自身的 layout.visibility） */
+    'visible'?: boolean;
+    /** 组级透明度 0..1，按图层类型缩放各透明度属性 */
+    'opacity'?: number;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
 declare var __VLS_1: {};
 type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_1) => any;
 };
-declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
-    visible: boolean;
-}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:visible": (value: boolean) => any;
+    "update:opacity": (value: number) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:visible"?: ((value: boolean) => any) | undefined;
+    "onUpdate:opacity"?: ((value: number) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/runtime/components/LayerGroup.vue

@@ -1,14 +1,54 @@
 <script setup>
-import { provide, toRef } from "vue";
+import { computed, inject, provide, reactive, shallowReactive, useId, watch } from "vue";
+import { clamp } from "@movk/core";
+import { useMap } from "../composables/useMap";
 import { LayerGroupKey } from "../domains/map/layer-group";
+import { getLayerTree } from "../domains/map/layer-tree";
+import { useStyleLayerAdoption } from "../domains/map/style-layers";
+import { deriveLegend } from "../utils/legend";
 const props = defineProps({
   beforeId: { type: String, required: false },
-  visible: { type: Boolean, required: false, default: true }
+  title: { type: String, required: false },
+  legend: { type: Array, required: false },
+  styleLayers: { type: Function, required: false }
 });
+const visible = defineModel("visible", { type: Boolean, ...{ default: true } });
+const opacity = defineModel("opacity", { type: Number, ...{ default: 1 } });
+const ctx = useMap();
+const parent = inject(LayerGroupKey, null);
+const effectiveVisible = computed(() => (parent?.visible.value ?? true) && visible.value);
+const effectiveOpacity = computed(() => (parent?.opacity.value ?? 1) * clamp(opacity.value, 0, 1));
+const layers = shallowReactive(/* @__PURE__ */ new Set());
+function registerLayer(descriptor) {
+  if (!props.title && parent) return parent.registerLayer(descriptor);
+  layers.add(descriptor);
+  return () => layers.delete(descriptor);
+}
 provide(LayerGroupKey, {
-  beforeId: toRef(props, "beforeId"),
-  visible: toRef(props, "visible")
+  beforeId: computed(() => props.beforeId ?? parent?.beforeId.value),
+  visible: effectiveVisible,
+  opacity: effectiveOpacity,
+  registerLayer
 });
+useStyleLayerAdoption(() => props.styleLayers, effectiveVisible, effectiveOpacity);
+const legendItems = computed(() => props.legend ?? deriveLegend([...layers].map((get) => get()), props.title ?? ""));
+const item = reactive({
+  id: useId(),
+  title: computed(() => props.title ?? ""),
+  visible,
+  opacity,
+  legend: legendItems,
+  setVisible: (value) => {
+    visible.value = value;
+  },
+  setOpacity: (value) => {
+    opacity.value = clamp(value, 0, 1);
+  }
+});
+watch(() => Boolean(props.title), (titled, _, onCleanup) => {
+  if (!titled) return;
+  onCleanup(getLayerTree(ctx).register(item.id, item));
+}, { immediate: true });
 </script>
 
 <template>

package/dist/runtime/components/LayerGroup.vue.d.ts

@@ -1,20 +1,33 @@
-/** 图层组：统一子图层的插入锚点与显隐（组开关优先于子图层自身 layout.visibility）。 */
+import type { LegendItem, StyleLayerPredicate } from '../types';
+/** 图层组：统一子图层的插入锚点、显隐与透明度；带 title 时进入图层树，供图层控件、图例与 useLayerTree 使用。 */
 type __VLS_Props = {
-    /** 组内图层缺省插入到该图层之前 */
+    /** 组内图层缺省插入到该图层之前；未设置时继承父组 */
     beforeId?: string;
-    /**
-     * 组级显隐
-     * @defaultValue true
-     */
-    visible?: boolean;
+    /** 组标题；设置后注册到图层树，出现在 MaplibreLayerControl、MaplibreLegend 与 useLayerTree 中 */
+    title?: string;
+    /** 图例项；省略时由子图层颜色推导 */
+    legend?: LegendItem[];
+    /** 认领底图样式自带的图层（按类型、source-layer 等匹配），与子图层一起受组的显隐与透明度控制 */
+    styleLayers?: StyleLayerPredicate;
 };
+type __VLS_ModelProps = {
+    /** 组级显隐（组开关优先于子图层自身的 layout.visibility） */
+    'visible'?: boolean;
+    /** 组级透明度 0..1，按图层类型缩放各透明度属性 */
+    'opacity'?: number;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
 declare var __VLS_1: {};
 type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_1) => any;
 };
-declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
-    visible: boolean;
-}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:visible": (value: boolean) => any;
+    "update:opacity": (value: number) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:visible"?: ((value: boolean) => any) | undefined;
+    "onUpdate:opacity"?: ((value: number) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/runtime/components/LottieMarker.d.vue.ts

@@ -1,7 +1,7 @@
 import type { LngLatLike } from 'maplibre-gl';
 /** Lottie 标记：在地图标记位用 lottie-web 渲染矢量动画（走 Marker DOM，非 icon 帧驱动）。 */
 type __VLS_Props = {
-    /** lottie 动画数据（JSON 对象）；与 path 二选一 */
+    /** lottie 动画数据（JSON 对象）；与 path 二选一，按引用比较，替换对象才重新加载 */
     animationData?: object;
     /** lottie 动画 URL；与 animationData 二选一 */
     path?: string;
@@ -40,11 +40,11 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {},
 }, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
     "onUpdate:lnglat"?: ((value: LngLatLike) => any) | undefined;
 }>, {
-    width: number;
-    height: number;
     loop: boolean;
     autoplay: boolean;
     speed: number;
+    width: number;
+    height: number;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/runtime/components/LottieMarker.vue

@@ -14,12 +14,16 @@ const props = defineProps({
 const lnglat = defineModel("lnglat", { type: [Object, Array], ...{ required: true } });
 const container = useTemplateRef("container");
 let anim;
-onMounted(() => {
+function load() {
+  anim?.destroy();
+  anim = void 0;
   if (!container.value) return;
   const base = { container: container.value, renderer: "svg", loop: props.loop, autoplay: props.autoplay };
   anim = props.path ? lottie.loadAnimation({ ...base, path: props.path }) : lottie.loadAnimation({ ...base, animationData: props.animationData });
   anim.setSpeed(props.speed);
-});
+}
+onMounted(load);
+watch([() => props.path, () => props.animationData, () => props.loop, () => props.autoplay], load);
 watch(() => props.speed, (speed) => anim?.setSpeed(speed));
 onUnmounted(() => anim?.destroy());
 </script>

package/dist/runtime/components/LottieMarker.vue.d.ts

@@ -1,7 +1,7 @@
 import type { LngLatLike } from 'maplibre-gl';
 /** Lottie 标记：在地图标记位用 lottie-web 渲染矢量动画（走 Marker DOM，非 icon 帧驱动）。 */
 type __VLS_Props = {
-    /** lottie 动画数据（JSON 对象）；与 path 二选一 */
+    /** lottie 动画数据（JSON 对象）；与 path 二选一，按引用比较，替换对象才重新加载 */
     animationData?: object;
     /** lottie 动画 URL；与 animationData 二选一 */
     path?: string;
@@ -40,11 +40,11 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {},
 }, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
     "onUpdate:lnglat"?: ((value: LngLatLike) => any) | undefined;
 }>, {
-    width: number;
-    height: number;
     loop: boolean;
     autoplay: boolean;
     speed: number;
+    width: number;
+    height: number;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/runtime/components/Map.d.vue.ts

@@ -4,7 +4,8 @@ type __VLS_Props = {
     /** 地图 id；省略时自动生成。提供后可经 useMaplibre(id) 外部访问 */
     mapId?: string;
     /**
-     * maplibre-gl Map 初始化选项（container 由组件接管）；缺省 style 时使用空白样式
+     * maplibre-gl Map 初始化选项（container 由组件接管）；缺省 style 时使用空白样式。
+     * 除 style 外仅在创建时读取，变更需配合 `:key` 重建
      * @see https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapOptions/
      */
     options?: MaplibreMapOptions;

package/dist/runtime/components/Map.vue

@@ -5,14 +5,10 @@ import { omitUndefined } from "@movk/core";
 import { LngLat } from "maplibre-gl";
 import { createMaplibreContext, MaplibreContextKey } from "../domains/map/context";
 import { createMaplibreGl } from "../domains/map/create-map";
-import { getMaplibreConfig } from "../domains/map/config";
+import { blankStyle } from "../domains/map/style";
 import { getMapContext, registerMap, unregisterMap } from "../domains/map/registry";
 import { bindMapEvents } from "../utils/events";
 defineOptions({ inheritAttrs: false });
-function blankStyle() {
-  const { glyphs } = getMaplibreConfig();
-  return { version: 8, ...glyphs ? { glyphs } : {}, sources: {}, layers: [] };
-}
 const props = defineProps({
   mapId: { type: String, required: false },
   options: { type: Object, required: false },
@@ -130,5 +126,5 @@ defineExpose({
 </template>
 
 <style>
-@layer components{:where(.movk-maplibre){height:100%;position:relative;width:100%}}.movk-maplibre>.movk-maplibre__container{inset:0;position:absolute}
+@layer components{:where(.movk-maplibre){height:100%;position:relative;width:100%}}.movk-maplibre{isolation:isolate}.movk-maplibre>.movk-maplibre__container{inset:0;position:absolute}
 </style>

package/dist/runtime/components/Map.vue.d.ts

@@ -4,7 +4,8 @@ type __VLS_Props = {
     /** 地图 id；省略时自动生成。提供后可经 useMaplibre(id) 外部访问 */
     mapId?: string;
     /**
-     * maplibre-gl Map 初始化选项（container 由组件接管）；缺省 style 时使用空白样式
+     * maplibre-gl Map 初始化选项（container 由组件接管）；缺省 style 时使用空白样式。
+     * 除 style 外仅在创建时读取，变更需配合 `:key` 重建
      * @see https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapOptions/
      */
     options?: MaplibreMapOptions;

package/dist/runtime/components/Marker.d.vue.ts

@@ -3,7 +3,8 @@ import type { LngLatLike, MarkerOptions, PopupOptions } from 'maplibre-gl';
 import type { PopupTrigger } from '../types';
 type __VLS_Props = {
     /**
-     * 标记选项；element 由默认插槽提供，无需在此传入
+     * 标记选项；element 由默认插槽提供，无需在此传入。
+     * 有 setter 的字段（rotation、draggable 等）增量更新，anchor、color、scale 变化时重建
      * @see https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MarkerOptions/
      */
     options?: Omit<MarkerOptions, 'element'>;