@movk/maplibre 1.0.0 → 1.2.0

package/dist/runtime/domains/map/draw-modes.js

@@ -0,0 +1,53 @@
+import {
+  TerraDrawCircleMode,
+  TerraDrawEllipseMode,
+  TerraDrawLineStringMode,
+  TerraDrawPointMode,
+  TerraDrawPolygonMode,
+  TerraDrawRectangleMode,
+  TerraDrawSectorMode,
+  TerraDrawSelectMode
+} from "terra-draw";
+import { logger } from "../../utils/logger.js";
+import { drawThemeStyles } from "./draw-theme.js";
+export const DRAW_MODE_NAMES = ["select", "point", "linestring", "polygon", "rectangle", "circle", "ellipse", "sector"];
+const EDITABLE_MODES = /* @__PURE__ */ new Set(["linestring", "polygon"]);
+const EDITABLE_COORDINATES = { draggable: true, deletable: true, midpoints: true };
+function selectFlags(names) {
+  return Object.fromEntries(names.filter((name) => name !== "select").map((name) => [name, {
+    feature: { draggable: true, ...EDITABLE_MODES.has(name) ? { coordinates: EDITABLE_COORDINATES } : {} }
+  }]));
+}
+function createMode(name, styles, names) {
+  switch (name) {
+    case "select":
+      return new TerraDrawSelectMode({ flags: selectFlags(names), styles: styles.select });
+    case "point":
+      return new TerraDrawPointMode({ styles: styles.point });
+    case "linestring":
+      return new TerraDrawLineStringMode({ styles: styles.linestring });
+    case "polygon":
+      return new TerraDrawPolygonMode({ styles: styles.polygon });
+    case "rectangle":
+      return new TerraDrawRectangleMode({ styles: styles.rectangle });
+    case "circle":
+      return new TerraDrawCircleMode({ styles: styles.circle });
+    case "ellipse":
+      return new TerraDrawEllipseMode({ styles: styles.ellipse });
+    case "sector":
+      return new TerraDrawSectorMode({ styles: styles.sector });
+  }
+}
+export function isDrawModeName(entry) {
+  return typeof entry === "string" && DRAW_MODE_NAMES.includes(entry);
+}
+export function resolveDrawModes(entries, theme) {
+  const valid = entries.filter((entry) => {
+    if (typeof entry !== "string" || isDrawModeName(entry)) return true;
+    logger.warn(`Draw: unknown mode "${entry}" skipped.`);
+    return false;
+  });
+  const styles = drawThemeStyles(theme);
+  const names = valid.map((entry) => typeof entry === "string" ? entry : entry.mode);
+  return valid.map((entry) => typeof entry === "string" ? createMode(entry, styles, names) : entry);
+}

package/dist/runtime/domains/map/draw-registry.d.ts

@@ -1,5 +1,4 @@
 import type { MaplibreDrawContext } from '../../types';
-export declare function registerDraw(context: MaplibreDrawContext): void;
-/** 按上下文身份注销：过渡期新控件可能先于旧控件卸载完成注册，按 id 删会误删新注册 */
-export declare function unregisterDraw(context: MaplibreDrawContext): void;
+/** 返回按身份校验的注销句柄：过渡期新控件可能先于旧控件卸载完成注册，按 id 删会误删新注册 */
+export declare function registerDraw(context: MaplibreDrawContext): () => void;
 export declare function getDrawContext(mapId: string): MaplibreDrawContext | undefined;

package/dist/runtime/domains/map/draw-registry.js

@@ -1,14 +1,11 @@
-import { shallowReactive } from "vue";
+import { createRegistry } from "@movk/core";
 import { logger } from "../../utils/logger.js";
-const registry = shallowReactive(/* @__PURE__ */ new Map());
+const registry = createRegistry({
+  reactive: true,
+  onDuplicate: (id) => logger.warn(`map "${id}" already has a <MaplibreDrawControl>; the latest one takes over.`)
+});
 export function registerDraw(context) {
-  if (registry.has(context.mapId)) {
-    logger.warn(`map "${context.mapId}" already has a <MaplibreDrawControl>; the latest one takes over.`);
-  }
-  registry.set(context.mapId, context);
-}
-export function unregisterDraw(context) {
-  if (registry.get(context.mapId) === context) registry.delete(context.mapId);
+  return registry.register(context.mapId, context);
 }
 export function getDrawContext(mapId) {
   return registry.get(mapId);

package/dist/runtime/domains/map/draw-theme.d.ts

@@ -0,0 +1,12 @@
+import type { GeoJSONStoreFeatures, HexColor } from 'terra-draw';
+import type { DrawModeName, DrawThemeOptions } from '../../types';
+type ColorStyle = (feature: GeoJSONStoreFeatures) => HexColor;
+type ModeStyles = Record<string, number | HexColor | ColorStyle>;
+/** 各内置模式的 terra-draw styles，键为模式名 */
+export type DrawThemeStyles = Record<DrawModeName, ModeStyles>;
+/**
+ * 生成 terra-draw 各内置模式的主题样式。
+ * 要素 `properties.color` 优先于主题色，便于按要素单独着色（配合 setFeatureProperty）。
+ */
+export declare function drawThemeStyles(options?: DrawThemeOptions): DrawThemeStyles;
+export {};

package/dist/runtime/domains/map/draw-toolbar.js

@@ -1,14 +1,15 @@
 const ICONS = {
-  select: '<path d="M6 3l12 9-5.5 1.2L15 20l-2.4 1-2.5-6.7L6 18z"/>',
-  point: '<circle cx="12" cy="12" r="4" fill="currentColor"/>',
-  linestring: '<path d="M4 19l6-10 5 6 5-10"/>',
-  polygon: '<path d="M5 18L4 8l8-4 8 5-3 10z"/>',
-  rectangle: '<rect x="4" y="6" width="16" height="12"/>',
-  circle: '<circle cx="12" cy="12" r="8"/>',
-  ellipse: '<ellipse cx="12" cy="12" rx="9" ry="6"/>',
-  sector: '<path d="M12 12h8a8 8 0 0 0-8-8z"/>',
-  trash: '<path d="M5 7h14M10 7V5h4v2M7 7l1 13h8l1-13"/>'
+  select: '<path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4.037 4.688a.495.495 0 0 1 .651-.651l16 6.5a.5.5 0 0 1-.063.947l-6.124 1.58a2 2 0 0 0-1.438 1.435l-1.579 6.126a.5.5 0 0 1-.947.063z"/>',
+  point: '<g fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"><path d="M20 10c0 4.993-5.539 10.193-7.399 11.799a1 1 0 0 1-1.202 0C9.539 20.193 4 14.993 4 10a8 8 0 0 1 16 0"/><circle cx="12" cy="10" r="3"/></g>',
+  linestring: '<g fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"><path d="M4.89 16.21l3.22-6.42M10.2 9.6l3.6 4.8M15.89 14.21l3.22-6.42"/><circle cx="4" cy="18" r="2"/><circle cx="9" cy="8" r="2"/><circle cx="15" cy="16" r="2"/><circle cx="20" cy="6" r="2"/></g>',
+  polygon: '<path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10.83 2.38a2 2 0 0 1 2.34 0l8 5.74a2 2 0 0 1 .73 2.25l-3.04 9.26a2 2 0 0 1-1.9 1.37H7.04a2 2 0 0 1-1.9-1.37L2.1 10.37a2 2 0 0 1 .73-2.25z"/>',
+  rectangle: '<rect width="20" height="12" x="2" y="6" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" rx="2"/>',
+  circle: '<circle cx="12" cy="12" r="10" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/>',
+  ellipse: '<ellipse cx="12" cy="12" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" rx="10" ry="6"/>',
+  sector: '<g fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"><path d="M21 12c.552 0 1.005-.449.95-.998a10 10 0 0 0-8.953-8.951c-.55-.055-.998.398-.998.95v8a1 1 0 0 0 1 1z"/><path d="M21.21 15.89A10 10 0 1 1 8 2.83"/></g>',
+  trash: '<path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 11v6m4-6v6m5-11v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6M3 6h18M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/>'
 };
+const FALLBACK_ICON = '<path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497zM15 5l4 4"/>';
 const LABELS = {
   select: "Select",
   point: "Point",
@@ -27,7 +28,7 @@ function createButton(name, dataset, onClick) {
   button.title = LABELS[name] ?? name;
   button.setAttribute("aria-label", button.title);
   Object.assign(button.dataset, dataset);
-  button.innerHTML = `<svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linejoin="round" stroke-linecap="round">${ICONS[name] ?? ""}</svg>`;
+  button.innerHTML = `<svg viewBox="0 0 24 24" width="18" height="18" aria-hidden="true">${ICONS[name] ?? FALLBACK_ICON}</svg>`;
   button.addEventListener("click", onClick);
   return button;
 }

package/dist/runtime/domains/map/layer-group.d.ts

@@ -1,9 +1,20 @@
 import type { InjectionKey, Ref } from 'vue';
+import type { LayerSpecification } from '@maplibre/maplibre-gl-style-spec';
+/** 子图层上报给所属组的描述，供图例推导 */
+export interface LayerDescriptor {
+    layerId: string;
+    type: LayerSpecification['type'];
+    paint?: Record<string, unknown>;
+}
 /** MaplibreLayerGroup 向子图层下发的组上下文 */
 export interface LayerGroupContext {
-    /** 组内图层缺省插入锚点（子图层自身 beforeId 优先） */
-    beforeId: Ref<string | undefined>;
-    /** 组级显隐开关 */
-    visible: Ref<boolean>;
+    /** 组内图层缺省插入锚点（子图层自身 beforeId 优先，未设置时继承父组） */
+    beforeId: Readonly<Ref<string | undefined>>;
+    /** 有效显隐：父组有效显隐与自身开关取与 */
+    visible: Readonly<Ref<boolean>>;
+    /** 有效透明度：父组有效透明度与自身透明度相乘 */
+    opacity: Readonly<Ref<number>>;
+    /** 上报子图层描述（取值函数，paint 变化随之反映），返回注销函数 */
+    registerLayer: (descriptor: () => LayerDescriptor) => () => void;
 }
 export declare const LayerGroupKey: InjectionKey<LayerGroupContext>;

package/dist/runtime/domains/map/layer-tree.d.ts

@@ -0,0 +1,3 @@
+import type { Registry } from '@movk/core';
+import type { LayerTreeItem, MaplibreContext } from '../../types';
+export declare function getLayerTree(context: MaplibreContext): Registry<LayerTreeItem>;

package/dist/runtime/domains/map/layer-tree.js

@@ -0,0 +1,10 @@
+import { createRegistry } from "@movk/core";
+const trees = /* @__PURE__ */ new WeakMap();
+export function getLayerTree(context) {
+  let tree = trees.get(context);
+  if (!tree) {
+    tree = createRegistry({ reactive: true });
+    trees.set(context, tree);
+  }
+  return tree;
+}

package/dist/runtime/domains/map/minimap.d.ts

@@ -0,0 +1,18 @@
+import type { IControl, StyleSpecification } from 'maplibre-gl';
+export interface MinimapControlOptions {
+    /** 鹰眼样式；省略时沿用主图样式并跟随其切换 */
+    style?: StyleSpecification | string;
+    /** 相对主图的缩放偏移 */
+    zoomOffset: number;
+    /** 宽度（px） */
+    width: number;
+    /** 高度（px） */
+    height: number;
+    /** 视口框颜色 */
+    color: string;
+}
+/**
+ * 鹰眼控件：容器内新建一个非交互的子地图，随主图移动同步相机并绘制主图视口框；
+ * 拖拽鹰眼按像素增量平移主图，单击则把主图中心缓动到点击处。
+ */
+export declare function createMinimapControl(options: MinimapControlOptions): IControl;

package/dist/runtime/domains/map/minimap.js

@@ -0,0 +1,86 @@
+import { omitUndefined } from "@movk/core";
+import { minimapZoom, viewportPolygon } from "../../utils/minimap.js";
+import { createMaplibreGl } from "./create-map.js";
+const SOURCE_ID = "movk-minimap-viewport";
+const FILL_ID = `${SOURCE_ID}-fill`;
+const LINE_ID = `${SOURCE_ID}-line`;
+export function createMinimapControl(options) {
+  let parent;
+  let mini;
+  let container;
+  function sync() {
+    if (!parent || !mini) return;
+    mini.jumpTo({ center: parent.getCenter(), zoom: minimapZoom(parent.getZoom(), options.zoomOffset) });
+    const source = mini.getSource(SOURCE_ID);
+    source?.setData(viewportPolygon(parent));
+  }
+  function addViewport() {
+    if (!mini || !parent) return;
+    mini.addSource(SOURCE_ID, { type: "geojson", data: viewportPolygon(parent) });
+    mini.addLayer({ id: FILL_ID, type: "fill", source: SOURCE_ID, paint: { "fill-color": options.color, "fill-opacity": 0.15 } });
+    mini.addLayer({ id: LINE_ID, type: "line", source: SOURCE_ID, paint: { "line-color": options.color, "line-width": 2 } });
+    sync();
+  }
+  function followParentStyle() {
+    if (parent && mini) mini.setStyle(parent.getStyle(), { diff: false });
+  }
+  let last;
+  let moved = false;
+  function onPointerDown(event) {
+    last = { x: event.clientX, y: event.clientY };
+    moved = false;
+    container?.setPointerCapture?.(event.pointerId);
+  }
+  function onPointerMove(event) {
+    if (!last || !parent || !mini) return;
+    const dx = event.clientX - last.x;
+    const dy = event.clientY - last.y;
+    last = { x: event.clientX, y: event.clientY };
+    if (!dx && !dy) return;
+    moved = true;
+    const origin = mini.project(mini.getCenter());
+    parent.jumpTo({ center: mini.unproject([origin.x + dx, origin.y + dy]) });
+  }
+  function onPointerUp(event) {
+    if (last && !moved && parent && mini && container) {
+      const rect = container.getBoundingClientRect();
+      parent.easeTo({ center: mini.unproject([event.clientX - rect.left, event.clientY - rect.top]) });
+    }
+    last = void 0;
+  }
+  return {
+    onAdd(map) {
+      parent = map;
+      container = document.createElement("div");
+      container.className = "maplibregl-ctrl maplibregl-ctrl-group movk-maplibre-minimap";
+      container.style.width = `${options.width}px`;
+      container.style.height = `${options.height}px`;
+      const style = options.style ?? (map.isStyleLoaded() ? map.getStyle() : void 0);
+      mini = createMaplibreGl(omitUndefined({
+        container,
+        style,
+        center: map.getCenter(),
+        zoom: minimapZoom(map.getZoom(), options.zoomOffset),
+        interactive: false,
+        attributionControl: false
+      }));
+      mini.on("style.load", addViewport);
+      map.on("move", sync);
+      if (!options.style) map.on("style.load", followParentStyle);
+      container.addEventListener("pointerdown", onPointerDown);
+      container.addEventListener("pointermove", onPointerMove);
+      container.addEventListener("pointerup", onPointerUp);
+      container.addEventListener("pointercancel", onPointerUp);
+      return container;
+    },
+    onRemove() {
+      parent?.off("move", sync);
+      parent?.off("style.load", followParentStyle);
+      mini?.remove();
+      container?.remove();
+      parent = void 0;
+      mini = void 0;
+      container = void 0;
+    }
+  };
+}

package/dist/runtime/domains/map/registry.js

@@ -1,9 +1,10 @@
-const registry = /* @__PURE__ */ new Map();
+import { createRegistry } from "@movk/core";
+const registry = createRegistry({ reactive: true });
 export function registerMap(context) {
-  registry.set(context.id, context);
+  registry.register(context.id, context);
 }
 export function unregisterMap(id) {
-  registry.delete(id);
+  registry.unregister(id);
 }
 export function getMapContext(id) {
   return registry.get(id);

package/dist/runtime/domains/map/style-layers.d.ts

@@ -0,0 +1,7 @@
+import type { Ref } from 'vue';
+import type { StyleLayerPredicate } from '../../types';
+/**
+ * 图层组认领底图样式自带的图层：按过滤函数匹配 style.load 快照中的图层，记录原值后按组的
+ * 有效显隐与透明度写入。每次样式重载重新匹配，卸载时恢复原值。
+ */
+export declare function useStyleLayerAdoption(predicate: () => StyleLayerPredicate | undefined, visible: Readonly<Ref<boolean>>, opacity: Readonly<Ref<number>>): void;

package/dist/runtime/domains/map/style-layers.js

@@ -0,0 +1,54 @@
+import { onUnmounted, watch } from "vue";
+import { useMap } from "../../composables/useMap.js";
+import { opacityPropsFor, scaleOpacity } from "../../utils/layer-opacity.js";
+export function useStyleLayerAdoption(predicate, visible, opacity) {
+  const ctx = useMap();
+  let adopted = /* @__PURE__ */ new Map();
+  function apply(map) {
+    for (const [id, original] of adopted) {
+      if (!map.getLayer(id)) continue;
+      map.setLayoutProperty(id, "visibility", visible.value ? original.visibility : "none");
+      for (const [key, value] of Object.entries(original.opacity)) {
+        map.setPaintProperty(id, key, scaleOpacity(value, opacity.value));
+      }
+    }
+  }
+  function restore(map) {
+    for (const [id, original] of adopted) {
+      if (!map.getLayer(id)) continue;
+      map.setLayoutProperty(id, "visibility", original.visibility);
+      for (const [key, value] of Object.entries(original.opacity)) map.setPaintProperty(id, key, value);
+    }
+  }
+  function adopt(map) {
+    adopted = /* @__PURE__ */ new Map();
+    const match = predicate();
+    if (!match) return;
+    const snapshot = new Set(ctx.styleLayerIds.value);
+    const layers = map.getStyle()?.layers ?? [];
+    for (const layer of layers) {
+      if (!snapshot.has(layer.id) || !match(layer)) continue;
+      const opacityValues = Object.fromEntries(
+        opacityPropsFor(layer.type).map((key) => [key, map.getPaintProperty(layer.id, key)])
+      );
+      adopted.set(layer.id, { visibility: map.getLayoutProperty(layer.id, "visibility"), opacity: opacityValues });
+    }
+    apply(map);
+  }
+  const stopReady = ctx.onReady(adopt);
+  watch([visible, opacity], () => {
+    const map = ctx.map.value;
+    if (map && ctx.isStyleReady.value) apply(map);
+  });
+  watch(predicate, () => {
+    const map = ctx.map.value;
+    if (!map || !ctx.isStyleReady.value) return;
+    restore(map);
+    adopt(map);
+  });
+  onUnmounted(() => {
+    stopReady();
+    const map = ctx.map.value;
+    if (map && ctx.isStyleReady.value) restore(map);
+  });
+}

package/dist/runtime/domains/map/style.d.ts

@@ -0,0 +1,3 @@
+import type { StyleSpecification } from '@maplibre/maplibre-gl-style-spec';
+/** MapLibre 无内置底图，缺省 style 时实例没有样式，style.load 永不触发；以空白样式兜底（如仅叠加天地图） */
+export declare function blankStyle(): StyleSpecification;

package/dist/runtime/domains/map/style.js

@@ -0,0 +1,5 @@
+import { getMaplibreConfig } from "./config.js";
+export function blankStyle() {
+  const { glyphs } = getMaplibreConfig();
+  return { version: 8, ...glyphs ? { glyphs } : {}, sources: {}, layers: [] };
+}

package/dist/runtime/domains/map/swipe.d.ts

@@ -0,0 +1,9 @@
+import type { Map as MaplibreMap } from 'maplibre-gl';
+/**
+ * 把对照图绑定到主图：相机、尺寸、投影单向跟随主图，露出区域内的鼠标事件转发给对照图，
+ * 对照图设置的光标同步到主图 canvas。返回解绑函数。
+ */
+export declare function bindSwipeOverlay(main: MaplibreMap, overlay: MaplibreMap, isRevealed: (point: {
+    x: number;
+    y: number;
+}) => boolean): () => void;

package/dist/runtime/domains/map/swipe.js

@@ -0,0 +1,62 @@
+import { MapMouseEvent } from "maplibre-gl";
+const FORWARDED_EVENTS = ["mousedown", "mouseup", "click", "dblclick", "mousemove", "contextmenu"];
+export function bindSwipeOverlay(main, overlay, isRevealed) {
+  const syncCamera = () => {
+    overlay.jumpTo({
+      center: main.getCenter(),
+      zoom: main.getZoom(),
+      bearing: main.getBearing(),
+      pitch: main.getPitch(),
+      padding: main.getPadding()
+    });
+  };
+  const syncSize = () => {
+    overlay.resize();
+  };
+  const syncProjection = () => {
+    const projection = main.getProjection();
+    if (projection) overlay.setProjection(projection);
+  };
+  let inside = false;
+  let mirroredCursor = "";
+  function mirrorCursor() {
+    const cursor = overlay.getCanvas().style.cursor;
+    if (cursor === mirroredCursor) return;
+    main.getCanvas().style.cursor = cursor;
+    mirroredCursor = cursor;
+  }
+  function leave(originalEvent) {
+    if (!inside) return;
+    inside = false;
+    overlay.fire(new MapMouseEvent("mouseout", overlay, originalEvent));
+    if (mirroredCursor) {
+      main.getCanvas().style.cursor = "";
+      mirroredCursor = "";
+    }
+  }
+  function forward(event) {
+    if (!isRevealed(event.point)) {
+      if (event.type === "mousemove") leave(event.originalEvent);
+      return;
+    }
+    inside = true;
+    overlay.fire(new MapMouseEvent(event.type, overlay, event.originalEvent));
+    if (event.type === "mousemove") mirrorCursor();
+  }
+  const onMainOut = (event) => leave(event.originalEvent);
+  main.on("move", syncCamera);
+  main.on("resize", syncSize);
+  main.on("projectiontransition", syncProjection);
+  overlay.on("style.load", syncProjection);
+  for (const type of FORWARDED_EVENTS) main.on(type, forward);
+  main.on("mouseout", onMainOut);
+  return () => {
+    main.off("move", syncCamera);
+    main.off("resize", syncSize);
+    main.off("projectiontransition", syncProjection);
+    overlay.off("style.load", syncProjection);
+    for (const type of FORWARDED_EVENTS) main.off(type, forward);
+    main.off("mouseout", onMainOut);
+    if (mirroredCursor) main.getCanvas().style.cursor = "";
+  };
+}

package/dist/runtime/index.css

@@ -1 +1 @@
-@import "maplibre-gl/dist/maplibre-gl.css";
+@import "maplibre-gl/dist/maplibre-gl.css";.movk-draw-toolbar__button{color:#333}.movk-draw-toolbar__button svg{display:block;margin:auto}.movk-draw-toolbar .movk-draw-toolbar__button[aria-pressed=true]:not(:disabled){background-color:var(--movk-draw-toolbar-active,#3b82f6);color:#fff}

package/dist/runtime/types/draw.d.ts

@@ -1,7 +1,40 @@
 import type { Ref } from 'vue';
-import type { TerraDraw, TerraDrawExtend } from 'terra-draw';
+import type { HexColor, TerraDraw, TerraDrawExtend } from 'terra-draw';
 import type { Feature, FeatureCollection, Geometry } from 'geojson';
 type FeatureId = TerraDrawExtend.FeatureId;
+/** 内置模式名：选择模式与全部绘制模式 */
+export type DrawModeName = 'select' | 'point' | 'linestring' | 'polygon' | 'rectangle' | 'circle' | 'ellipse' | 'sector';
+/** terra-draw 模式实例（绘制或选择模式） */
+export type DrawMode = TerraDrawExtend.TerraDrawBaseDrawMode<TerraDrawExtend.CustomStyling>;
+/** 模式项：内置模式名（套用主题）或自定义 terra-draw 实例（原样使用） */
+export type DrawModeEntry = DrawModeName | DrawMode;
+export interface DrawThemeOptions {
+    /**
+     * 非激活态主色，要素 properties.color 优先
+     * @defaultValue '#3b82f6'
+     */
+    color?: HexColor;
+    /**
+     * 激活态（绘制辅助点/选中）主色
+     * @defaultValue '#f59e0b'
+     */
+    activeColor?: HexColor;
+    /**
+     * 多边形填充不透明度
+     * @defaultValue 0.1
+     */
+    fillOpacity?: number;
+    /**
+     * 线宽
+     * @defaultValue 2
+     */
+    lineWidth?: number;
+    /**
+     * 顶点圆半径
+     * @defaultValue 5
+     */
+    vertexRadius?: number;
+}
 /**
  * 由 MaplibreDrawControl 下发的绘制上下文。
  * 子树内经 useMaplibreDraw() 注入，子树外经 useMaplibreDraw({ mapId }) 查注册表。

package/dist/runtime/types/index.d.ts

@@ -1,3 +1,4 @@
 export type * from './draw';
+export type * from './layer';
 export type * from './map';
 export type * from './tianditu';

package/dist/runtime/types/layer.d.ts

@@ -0,0 +1,40 @@
+import type { LayerSpecification, StyleSpecification } from '@maplibre/maplibre-gl-style-spec';
+/** 图例项：面、线、点为单色色块，gradient 为连续色带 */
+export interface LegendItem {
+    /** 标签文字 */
+    label: string;
+    /** 色块形状 */
+    type: 'fill' | 'line' | 'circle' | 'gradient';
+    /** 单色色块颜色 */
+    color?: string;
+    /** 渐变色带颜色，按顺序 */
+    colors?: string[];
+}
+/** 认领底图样式图层的过滤函数，按图层特征（类型、source-layer 等）匹配 */
+export type StyleLayerPredicate = (layer: LayerSpecification) => boolean;
+/** 图层树中的一项，对应一个带 title 的 MaplibreLayerGroup */
+export interface LayerTreeItem {
+    /** 组的唯一标识 */
+    id: string;
+    /** 组标题 */
+    title: string;
+    /** 组自身的显隐开关 */
+    visible: boolean;
+    /** 组自身的透明度 0..1 */
+    opacity: number;
+    /** 图例项：legend prop 优先，否则由子图层颜色推导 */
+    legend: LegendItem[];
+    /** 写回组的 v-model:visible */
+    setVisible: (visible: boolean) => void;
+    /** 写回组的 v-model:opacity */
+    setOpacity: (opacity: number) => void;
+}
+/** 底图切换项 */
+export interface BasemapItem {
+    /** 显示名称 */
+    label: string;
+    /** 底图样式（对象或样式 URL）；天地图可用 tiandituStyle() 生成 */
+    style: StyleSpecification | string;
+    /** 缩略图地址；任一项提供时以网格展示 */
+    thumbnail?: string;
+}

package/dist/runtime/types/map.d.ts

@@ -35,6 +35,12 @@ export interface MaplibreContext {
     map: ShallowRef<MaplibreMap | undefined>;
     /** 样式是否已加载完成 */
     isLoaded: Ref<boolean>;
+    /** 当前样式是否已解析（style.load 置真、styledataloading 置假）；不受瓦片/源加载影响 */
+    isStyleReady: Ref<boolean>;
+    /** 当前样式自带的图层 id（每次 style.load 时快照），不含运行时由组件添加的图层 */
+    styleLayerIds: Readonly<ShallowRef<readonly string[]>>;
+    /** 地图实例创建后 resolve；Marker、Popup、控件、相机等无需等待瓦片加载的操作用它 */
+    whenAttached: () => Promise<MaplibreMap>;
     /** 样式首次加载完成时 resolve */
     whenLoaded: () => Promise<MaplibreMap>;
     /**

package/dist/runtime/utils/cog.d.ts

@@ -0,0 +1,2 @@
+/** 注册 `cog://` 协议（全局单例、幂等），用于直接加载 Cloud Optimized GeoTIFF */
+export declare function registerCogProtocol(): void;

package/dist/runtime/utils/cog.js

@@ -0,0 +1,9 @@
+import { addProtocol } from "maplibre-gl";
+import { cogProtocol } from "@geomatico/maplibre-cog-protocol";
+import { defineGlobalSingleton } from "@movk/core";
+export function registerCogProtocol() {
+  defineGlobalSingleton("movk-maplibre:protocol:cog", () => {
+    addProtocol("cog", cogProtocol);
+    return true;
+  });
+}

package/dist/runtime/utils/effects.js

@@ -1,3 +1,4 @@
+import { clamp } from "@movk/core";
 export function arcLine(from, to, options = {}) {
   const curvature = options.curvature ?? 0.3;
   const segments = options.segments ?? 64;
@@ -48,7 +49,7 @@ export function ringFade(progress) {
 export function trailGradient(head, trailLength, color) {
   const eps = 1e-4;
   const transparent = "rgba(0, 0, 0, 0)";
-  const h = Math.min(Math.max(head, eps), 1);
+  const h = clamp(head, eps, 1);
   const tail = Math.max(h - Math.max(trailLength, eps), 0);
   const expr = ["interpolate", ["linear"], ["line-progress"], tail, transparent, h, color];
   if (h + eps < 1) expr.push(h + eps, transparent);

package/dist/runtime/utils/events.d.ts

@@ -4,3 +4,9 @@ import type { Map as MaplibreMap } from 'maplibre-gl';
  * 传入 layerId 时绑定到指定图层（用于图层级交互事件）。
  */
 export declare function bindMapEvents<E extends string>(map: MaplibreMap, events: readonly E[], handler: (type: E, event: unknown) => void, layerId?: string): () => void;
+/**
+ * 目标图层所用 source 的数据变化（setData / setTiles 等）且重新加载完成后，在下一次 render 时回调，返回解绑函数。
+ * 仅响应 sourceDataType 为 'content' 的事件，瓦片加载不会触发；同一轮多次变化只回调一次。
+ * 不依赖 idle：动效组件逐帧重绘时地图不会进入 idle。
+ */
+export declare function onLayerDataChange(map: MaplibreMap, layerId: string, handler: () => void): () => void;

package/dist/runtime/utils/events.js

@@ -18,3 +18,28 @@ export function bindMapEvents(map, events, handler, layerId) {
     }
   };
 }
+export function onLayerDataChange(map, layerId, handler) {
+  let pendingSource;
+  function stop() {
+    map.off("render", onRender);
+    pendingSource = void 0;
+  }
+  function onRender() {
+    if (!pendingSource) return;
+    if (!map.getSource(pendingSource)) return stop();
+    if (!map.isSourceLoaded(pendingSource)) return;
+    stop();
+    handler();
+  }
+  const onSourceData = (event) => {
+    if (pendingSource || event.sourceDataType !== "content") return;
+    if (event.sourceId !== map.getLayer(layerId)?.source) return;
+    pendingSource = event.sourceId;
+    map.on("render", onRender);
+  };
+  map.on("sourcedata", onSourceData);
+  return () => {
+    map.off("sourcedata", onSourceData);
+    stop();
+  };
+}

package/dist/runtime/utils/frame-icon.d.ts

@@ -11,11 +11,8 @@ export interface FrameStyleImageOptions {
     frames: () => ImageData[];
     /** 取地图实例以触发重绘 */
     getMap: () => MaplibreMap | undefined;
-    /**
-     * 固定帧率；durations 缺省时生效
-     * @defaultValue 12
-     */
-    fps?: number;
+    /** 固定帧率（响应式取值），durations 缺省时生效；省略时为 12 */
+    fps?: () => number;
     /** 每帧时长 ms（响应式取值），优先于 fps */
     durations?: () => number[] | undefined;
 }