@orbat-mapper/tactical-draw-adapter-maplibre 0.5.0 → 0.6.0

package/dist/index.d.mts

@@ -143,6 +143,13 @@ interface MapLibreLayerHandle {
   sourceId: string;
   /** MapLibre layer ids created for this logical layer (fill, line, circle, symbol) */
   mlLayerIds: string[];
+  /**
+   * Anchor for overlay-band bundle layers while terrain is active — this
+   * handle's own `-circle` layer (ADR-0057). Stored explicitly rather than
+   * derived from `mlLayerIds` by position/suffix so the terrain-banding code
+   * doesn't depend on `createLayer`'s layer-creation order.
+   */
+  overlayAnchorId: string;
   groupBundles: Map<string, MapLibreGroupBundle>;
   groupOrder: string[];
   nextGroupBundleId: number;
@@ -214,13 +221,33 @@ interface MapLibreAdapterOptions {
    * the refit until the animation ends.
    */
   viewChangeMode?: "continuous" | "settle";
+  /**
+   * While MapLibre terrain is active, paint fill/line layers in one band below
+   * circle/icon/text/pin layers so terrain draping stays in few passes
+   * (ADR-0057). `false` keeps exact per-graphic paint order under terrain, at
+   * one draping pass per graphic. @default true
+   */
+  terrainBanding?: boolean;
 }
 declare class MapLibreAdapter extends BaseMapAdapter<MapLibreLayerHandle, MapLibreEventToken, MapLibreViewToken> {
   private map;
   private readonly viewChangeMode;
   private readonly pendingIconImages;
   readonly scalesGroundPointSymbolsNatively = true;
+  private terrainActive;
+  private terrainBanding;
+  private readonly handleTerrainChange;
   constructor(map: maplibregl.Map, options?: MapLibreAdapterOptions);
+  /** Switches `terrainBanding` at runtime, re-banding every group if the effective state changes. */
+  setTerrainBanding(enabled: boolean): void;
+  protected destroyEngineResources(): void;
+  /**
+   * Insertion anchor for a new bundle layer: below the handle's layers, or —
+   * for an overlay-band layer under terrain — below the overlay anchor, so it
+   * never lands between draped layers and fragments a render-to-texture stack
+   * (ADR-0057).
+   */
+  private insertionAnchor;
   private toContinuousLng;
   protected createLayer(layerId: LayerId, style?: StyleOptions): MapLibreLayerHandle;
   protected destroyLayer(handle: MapLibreLayerHandle): void;
@@ -234,6 +261,21 @@ declare class MapLibreAdapter extends BaseMapAdapter<MapLibreLayerHandle, MapLib
   private updateSurfaceSizing;
   private buildGroupLayer;
   private updateGroupBundleSource;
+  /**
+   * Reorders bundle layers below `handle.mlLayerIds`. Walks groups back to
+   * front with a `beforeId` cursor, the same LIS-based stable-subset
+   * optimization as before.
+   *
+   * While terrain is active (ADR-0057), bundle layers instead split into two
+   * independently-tracked bands so every graphic contributes at most two
+   * render-to-texture stacks instead of one per graphic: a draped band
+   * (image overlays, fill/fill-pattern/line surfaces) anchored below the
+   * handle's own `-fill` layer, and an overlay band (the pin layer,
+   * circle/icon/text surfaces) anchored below the handle's own `-circle`
+   * layer. Without terrain, both cursors stay equal throughout, collapsing
+   * back to the single-cursor algorithm and the exact atomic per-graphic
+   * order (ADR-0039).
+   */
   private orderGroupBundles;
   private nativeLayerIds;
   /**

package/dist/index.mjs

@@ -1305,13 +1305,44 @@ function coordinatesEqual(a, b) {
 	}
 	return true;
 }
-function firstBundleLayerId(bundle) {
-	for (const overlay of bundle.overlays.values()) return overlay.layerId;
+/**
+* Paint channels MapLibre renders into a terrain render-to-texture stack
+* (background/fill/line/raster/hillshade) rather than directly onto the
+* screen. See ADR-0057.
+*/
+const DRAPED_CHANNELS = new Set([
+	"fill",
+	"fill-pattern",
+	"line"
+]);
+function isDrapedChannel(channel) {
+	return DRAPED_CHANNELS.has(channel);
+}
+/**
+* Bottom-most layer of a bundle, used as the next (earlier) group's anchor in
+* `orderGroupBundles`. With a `band` (terrain active, ADR-0057), only that
+* band's layers count: image overlays are always draped, the pin layer is
+* always overlay, and paint surfaces follow `isDrapedChannel`.
+*/
+function firstBundleLayerId(bundle, band) {
+	if (bundle.pinLayer && band !== "draped") return bundle.pinLayer.id;
+	if (band !== "overlay") for (const overlay of bundle.overlays.values()) return overlay.layerId;
 	for (const key of bundle.paintOrder) {
 		const surface = bundle.paintSurfaces.get(key);
-		if (surface) return surface.layerId;
+		if (!surface) continue;
+		if (!band || isDrapedChannel(surface.channel) === (band === "draped")) return surface.layerId;
 	}
 }
+/** Hides an always-empty handle-level anchor layer; see `createLayer`. */
+function hiddenLayer(layer) {
+	return {
+		...layer,
+		layout: {
+			..."layout" in layer ? layer.layout : {},
+			visibility: "none"
+		}
+	};
+}
 function sameOrder(a, b) {
 	if (a.length !== b.length) return false;
 	for (let index = 0; index < a.length; index++) if (a[index] !== b[index]) return false;
@@ -1915,10 +1946,38 @@ var MapLibreAdapter = class extends BaseMapAdapter {
 	viewChangeMode;
 	pendingIconImages = /* @__PURE__ */ new Set();
 	scalesGroundPointSymbolsNatively = true;
+	terrainActive = false;
+	terrainBanding;
+	handleTerrainChange = () => {
+		const active = this.terrainBanding && !!this.map.getTerrain?.();
+		if (active === this.terrainActive) return;
+		this.terrainActive = active;
+		for (const handle of this.layers.values()) this.orderGroupBundles(handle, handle.groupOrder, handle.groupOrder, new Set(handle.groupOrder));
+	};
 	constructor(map, options = {}) {
 		super();
 		this.map = map;
 		this.viewChangeMode = options.viewChangeMode ?? "continuous";
+		this.terrainBanding = options.terrainBanding ?? true;
+		this.handleTerrainChange();
+		this.map.on("terrain", this.handleTerrainChange);
+	}
+	/** Switches `terrainBanding` at runtime, re-banding every group if the effective state changes. */
+	setTerrainBanding(enabled) {
+		this.terrainBanding = enabled;
+		this.handleTerrainChange();
+	}
+	destroyEngineResources() {
+		this.map.off("terrain", this.handleTerrainChange);
+	}
+	/**
+	* Insertion anchor for a new bundle layer: below the handle's layers, or —
+	* for an overlay-band layer under terrain — below the overlay anchor, so it
+	* never lands between draped layers and fragments a render-to-texture stack
+	* (ADR-0057).
+	*/
+	insertionAnchor(handle, draped) {
+		return this.terrainActive && !draped ? handle.overlayAnchorId : handle.mlLayerIds[0];
 	}
 	toContinuousLng(lng) {
 		return nearestWorldCopyLng(lng, this.map.getCenter().lng);
@@ -1932,25 +1991,25 @@ var MapLibreAdapter = class extends BaseMapAdapter {
 		});
 		const mlLayerIds = [];
 		const fillId = `${layerId}-fill`;
-		this.map.addLayer({
+		this.map.addLayer(hiddenLayer({
 			id: fillId,
 			type: "fill",
 			source: sourceId,
 			filter: buildFillFilter(false),
 			paint: buildFillPaint(style)
-		});
+		}));
 		mlLayerIds.push(fillId);
 		const fillPatternId = `${layerId}-fill-pattern`;
-		this.map.addLayer({
+		this.map.addLayer(hiddenLayer({
 			id: fillPatternId,
 			type: "fill",
 			source: sourceId,
 			filter: buildFillFilter(true),
 			paint: FILL_PATTERN_PAINT
-		});
+		}));
 		mlLayerIds.push(fillPatternId);
 		const lineId = `${layerId}-line`;
-		this.map.addLayer({
+		this.map.addLayer(hiddenLayer({
 			id: lineId,
 			type: "line",
 			source: sourceId,
@@ -1972,28 +2031,29 @@ var MapLibreAdapter = class extends BaseMapAdapter {
 				"line-cap": "round",
 				"line-join": "round"
 			}
-		});
+		}));
 		mlLayerIds.push(lineId);
 		const circleId = `${layerId}-circle`;
-		this.map.addLayer({
+		this.map.addLayer(hiddenLayer({
 			id: circleId,
 			type: "circle",
 			source: sourceId,
 			filter: buildCirclePointFilter(style),
 			paint: buildCirclePaint(style)
-		});
+		}));
 		mlLayerIds.push(circleId);
 		const iconId = `${layerId}-icon`;
-		this.map.addLayer(buildIconLayer(iconId, sourceId));
+		this.map.addLayer(hiddenLayer(buildIconLayer(iconId, sourceId)));
 		mlLayerIds.push(iconId);
 		if (style?.text) {
 			const symbolId = `${layerId}-symbol`;
-			this.map.addLayer(buildSymbolLayer(symbolId, sourceId, style.text));
+			this.map.addLayer(hiddenLayer(buildSymbolLayer(symbolId, sourceId, style.text)));
 			mlLayerIds.push(symbolId);
 		}
 		return {
 			sourceId,
 			mlLayerIds,
+			overlayAnchorId: circleId,
 			groupBundles: /* @__PURE__ */ new Map(),
 			groupOrder: [],
 			nextGroupBundleId: 0,
@@ -2062,7 +2122,7 @@ var MapLibreAdapter = class extends BaseMapAdapter {
 			if (group.pinBatch) {
 				if (!bundle.pinLayer) {
 					const custom = new PinLayer(`${bundle.sourceId}-pins`, handle.pinResources, this.emitPinStatus);
-					this.map.addLayer(custom, handle.mlLayerIds[0]);
+					this.map.addLayer(custom, this.insertionAnchor(handle, false));
 					bundle.pinLayer = custom;
 					bundlesNeedingOrder.add(group.id);
 				}
@@ -2236,7 +2296,7 @@ var MapLibreAdapter = class extends BaseMapAdapter {
 					featureId
 				]
 			};
-			this.map.addLayer(layer, handle.mlLayerIds[0]);
+			this.map.addLayer(layer, this.insertionAnchor(handle, isDrapedChannel(channel)));
 			bundle.paintSurfaces.set(key, {
 				layerId,
 				channel,
@@ -2332,23 +2392,44 @@ var MapLibreAdapter = class extends BaseMapAdapter {
 		bundle.sourceInitialized = true;
 		if (isPromiseLike(result)) Promise.resolve(result).catch(() => {});
 	}
+	/**
+	* Reorders bundle layers below `handle.mlLayerIds`. Walks groups back to
+	* front with a `beforeId` cursor, the same LIS-based stable-subset
+	* optimization as before.
+	*
+	* While terrain is active (ADR-0057), bundle layers instead split into two
+	* independently-tracked bands so every graphic contributes at most two
+	* render-to-texture stacks instead of one per graphic: a draped band
+	* (image overlays, fill/fill-pattern/line surfaces) anchored below the
+	* handle's own `-fill` layer, and an overlay band (the pin layer,
+	* circle/icon/text surfaces) anchored below the handle's own `-circle`
+	* layer. Without terrain, both cursors stay equal throughout, collapsing
+	* back to the single-cursor algorithm and the exact atomic per-graphic
+	* order (ADR-0039).
+	*/
 	orderGroupBundles(handle, previousGroupIds, desiredGroupIds, forcedGroupIds) {
-		let beforeId = handle.mlLayerIds[0];
-		if (!beforeId) return;
+		const rootBeforeId = handle.mlLayerIds[0];
+		if (!rootBeforeId) return;
+		let drapedBeforeId = rootBeforeId;
+		let overlayBeforeId = this.terrainActive ? handle.overlayAnchorId : rootBeforeId;
 		const stableGroupIds = sameOrder(previousGroupIds, desiredGroupIds) ? null : longestStableGroupIds(previousGroupIds, desiredGroupIds);
 		for (let index = desiredGroupIds.length - 1; index >= 0; index--) {
 			const groupId = desiredGroupIds[index];
 			const bundle = handle.groupBundles.get(groupId);
 			if (!bundle) continue;
 			if (forcedGroupIds.has(groupId) || stableGroupIds !== null && !stableGroupIds.has(groupId)) {
-				if (bundle.pinLayer && this.map.getLayer(bundle.pinLayer.id)) this.map.moveLayer(bundle.pinLayer.id, beforeId);
-				for (const overlay of bundle.overlays.values()) if (this.map.getLayer(overlay.layerId)) this.map.moveLayer(overlay.layerId, beforeId);
+				if (bundle.pinLayer && this.map.getLayer(bundle.pinLayer.id)) this.map.moveLayer(bundle.pinLayer.id, overlayBeforeId);
+				for (const overlay of bundle.overlays.values()) if (this.map.getLayer(overlay.layerId)) this.map.moveLayer(overlay.layerId, drapedBeforeId);
 				for (const key of bundle.paintOrder) {
 					const surface = bundle.paintSurfaces.get(key);
-					if (surface && this.map.getLayer(surface.layerId)) this.map.moveLayer(surface.layerId, beforeId);
+					if (!surface || !this.map.getLayer(surface.layerId)) continue;
+					this.map.moveLayer(surface.layerId, isDrapedChannel(surface.channel) ? drapedBeforeId : overlayBeforeId);
 				}
 			}
-			beforeId = bundle.pinLayer?.id ?? firstBundleLayerId(bundle) ?? beforeId;
+			if (this.terrainActive) {
+				drapedBeforeId = firstBundleLayerId(bundle, "draped") ?? drapedBeforeId;
+				overlayBeforeId = firstBundleLayerId(bundle, "overlay") ?? overlayBeforeId;
+			} else drapedBeforeId = overlayBeforeId = firstBundleLayerId(bundle) ?? drapedBeforeId;
 		}
 	}
 	nativeLayerIds(handle) {
@@ -2589,7 +2670,7 @@ var MapLibreAdapter = class extends BaseMapAdapter {
 		for (const bundle of handle.groupBundles.values()) for (const surface of bundle.paintSurfaces.values()) this.applyChannelStyle(surface.layerId, surface.channel, style, resolvedStyle, surface.featureId);
 		if (style.text && !handle.mlLayerIds.some((id) => id.endsWith("-symbol"))) {
 			const symbolId = `${layerId}-symbol`;
-			this.map.addLayer(buildSymbolLayer(symbolId, handle.sourceId, resolvedStyle.text));
+			this.map.addLayer(hiddenLayer(buildSymbolLayer(symbolId, handle.sourceId, resolvedStyle.text)));
 			handle.mlLayerIds.push(symbolId);
 		}
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orbat-mapper/tactical-draw-adapter-maplibre",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "MapLibre GL JS engine adapter for @orbat-mapper/tactical-draw. Draw and edit tactical control measures (MIL-STD-2525 / APP-6) on a MapLibre map.",
   "license": "MIT",
   "author": "Orbat Mapper",
@@ -38,7 +38,7 @@
   },
   "dependencies": {
     "@orbat-mapper/control-measures": "^0.27.0",
-    "@orbat-mapper/tactical-draw": "^0.10.0"
+    "@orbat-mapper/tactical-draw": "^0.10.1"
   },
   "peerDependencies": {
     "maplibre-gl": ">=5.8.0 <7.0.0"