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

package/dist/index.d.mts

@@ -62,6 +62,20 @@ declare class PinLayer implements CustomLayerInterface {
   private atlas;
   private pins;
   private ranges;
+  private instanceData;
+  private sortedData;
+  private paintOrder;
+  private gpuOffsets;
+  private depths;
+  private sortMatrix;
+  private sortGlobeMatrix;
+  private sortTransition;
+  private sortWorld;
+  private sortDirty;
+  /** View-wide far-to-near paint order; `false` restores canonical layer order. */
+  private depthSorted;
+  /** Hoisted out of the per-frame sort so no comparator is allocated while panning. */
+  private comparePaintOrder;
   private version;
   private resourceRevision;
   private needsDepth;
@@ -98,6 +112,8 @@ declare class PinLayer implements CustomLayerInterface {
   private buildPin;
   private rebuild;
   render(context: WebGLRenderingContext | WebGL2RenderingContext, input: CustomRenderMethodInput): void;
+  /** Reorder existing instances only when camera/data changes, preserving atlas batches. */
+  private updatePaintOrder;
   private draw;
   /** On-demand GPU pick shares the visual shader including alpha and terrain mask. */
   pick(pixel: PixelCoordinate, tolerance?: number): string | null;
@@ -127,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;
@@ -198,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;
@@ -218,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

@@ -327,6 +327,12 @@ const PIN_GLOBE_RADIUS = EARTH_RADIUS;
 function pinMercator(position) {
 	return MercatorCoordinate.fromLngLat([position[0], Math.max(-89.999999, Math.min(89.999999, position[1]))]);
 }
+/** Scratch sphere position reused by the per-pin, per-frame depth() path. */
+const depthSphere = [
+	0,
+	0,
+	0
+];
 const multiply = (m, v) => [
 	0,
 	1,
@@ -367,6 +373,34 @@ var PinProjection = class {
 			this.matrix[12 + row] = fallback[12 + row] + fallback[row] * xyScale * origin[0] * world + fallback[4 + row] * xyScale * origin[1] * world;
 		}
 	}
+	/**
+	* Globe-sphere position for a world/elevation anchor, written into `out` so the
+	* per-pin depth path stays allocation-free. Single source of the sphere maths
+	* shared with project().
+	*/
+	sphere(worldX, worldY, elevation, out) {
+		const angle = (worldX / this.world + this.origin[0]) * Math.PI * 2 + Math.PI;
+		const t = Math.exp(Math.PI - (worldY / this.world + this.origin[1]) * Math.PI * 2);
+		const scale = 1 + elevation / PIN_GLOBE_RADIUS;
+		out[0] = Math.sin(angle) * 2 * t / (t * t + 1) * scale;
+		out[1] = (t * t - 1) / (t * t + 1) * scale;
+		out[2] = Math.cos(angle) * 2 * t / (t * t + 1) * scale;
+		return out;
+	}
+	/** Allocation-free depth-only projection for sorting large pin batches. */
+	depth(worldX, worldY, elevation) {
+		const m = this.matrix;
+		let z = m[2] * worldX + m[6] * worldY + m[10] * elevation + m[14];
+		let w = m[3] * worldX + m[7] * worldY + m[11] * elevation + m[15];
+		if (this.transition !== 0) {
+			const s = this.sphere(worldX, worldY, elevation, depthSphere);
+			const g = this.globeMatrix;
+			const blend = this.transition;
+			z = z * (1 - blend) + (g[2] * s[0] + g[6] * s[1] + g[10] * s[2] + g[14]) * blend;
+			w = w * (1 - blend) + (g[3] * s[0] + g[7] * s[1] + g[11] * s[2] + g[15]) * blend;
+		}
+		return z / w;
+	}
 	project(worldX, worldY, elevation) {
 		const flat = multiply(this.matrix, [
 			worldX,
@@ -378,16 +412,11 @@ var PinProjection = class {
 			clip: flat,
 			horizon: 1
 		};
-		const x = worldX / this.world + this.origin[0];
-		const y = worldY / this.world + this.origin[1];
-		const angle = x * Math.PI * 2 + Math.PI;
-		const t = Math.exp(Math.PI - y * Math.PI * 2);
-		const scale = 1 + elevation / PIN_GLOBE_RADIUS;
-		const sphere = [
-			Math.sin(angle) * 2 * t / (t * t + 1),
-			(t * t - 1) / (t * t + 1),
-			Math.cos(angle) * 2 * t / (t * t + 1)
-		].map((n) => n * scale);
+		const sphere = this.sphere(worldX, worldY, elevation, [
+			0,
+			0,
+			0
+		]);
 		const globe = multiply(this.globeMatrix, [...sphere, 1]);
 		const horizon = 1 - (1 - sphere.reduce((sum, n, i) => sum + n * this.clippingPlane[i], this.clippingPlane[3])) * Math.max(0, (this.transition - .2) / .8);
 		return {
@@ -439,22 +468,34 @@ function shader(gl, type, source) {
 	}
 	return s;
 }
+/** Copies `source` into `cache`, reporting whether any element differed. */
+function cacheChanged(cache, source) {
+	let changed = false;
+	for (let i = 0; i < cache.length; i++) {
+		if (cache[i] !== source[i]) changed = true;
+		cache[i] = source[i];
+	}
+	return changed;
+}
 const elevationOrSeaLevel = (value) => Number.isFinite(value) ? value : 0;
 /**
 * Appends one instance's worth of vertex-shader input to `data` and extends `ranges`
 * accordingly. Hoisted out of rebuild()'s per-pin loop (ADR n/a) so pushing 10k+ pins
 * never allocates a fresh closure per pin — every varying value is an explicit param.
 */
-function appendPinInstance(data, ranges, image, highlightOnly, instanceId, occlusionTerrain, kind, shape, color, a, target, mode) {
-	if (highlightOnly && kind !== PIN_KIND.HIGHLIGHT) return;
-	const first = data.length / STRIDE;
+/** Extends the trailing draw range when it shares an atlas page, else starts a new one. */
+function pushRange(ranges, page, first, count) {
 	const previous = ranges[ranges.length - 1];
-	if (previous?.page === image.page) previous.count++;
+	if (previous?.page === page) previous.count += count;
 	else ranges.push({
-		page: image.page,
+		page,
 		first,
-		count: 1
+		count
 	});
+}
+function appendPinInstance(data, ranges, image, highlightOnly, instanceId, occlusionTerrain, kind, shape, color, a, target, mode) {
+	if (highlightOnly && kind !== PIN_KIND.HIGHLIGHT) return;
+	pushRange(ranges, image.page, data.length / STRIDE, 1);
 	data.push(...a, ...target, ...shape, ...color, ...image.uv, kind, mode, occlusionTerrain, instanceId);
 }
 /**
@@ -493,6 +534,20 @@ var PinLayer = class {
 	atlas = new PinAtlas();
 	pins = [];
 	ranges = [];
+	instanceData = new Float32Array(0);
+	sortedData = new Float32Array(0);
+	paintOrder = [];
+	gpuOffsets = [];
+	depths = new Float64Array(0);
+	sortMatrix = new Float64Array(16).fill(NaN);
+	sortGlobeMatrix = new Float64Array(16).fill(NaN);
+	sortTransition = NaN;
+	sortWorld = NaN;
+	sortDirty = true;
+	/** View-wide far-to-near paint order; `false` restores canonical layer order. */
+	depthSorted = false;
+	/** Hoisted out of the per-frame sort so no comparator is allocated while panning. */
+	comparePaintOrder = (a, b) => (this.depthSorted ? this.depths[b] - this.depths[a] : 0) || a - b;
 	version = 0;
 	resourceRevision = -1;
 	needsDepth = false;
@@ -646,6 +701,7 @@ var PinLayer = class {
 		}
 		this.pins = pins;
 		this.prioritizesSelection = pins[0]?.presentation.prioritizePins ?? false;
+		this.depthSorted = pins[0]?.presentation.depthSort ?? false;
 		if (this.elevationCache.size > pins.length * 60 + 1e3) this.elevationCache.clear();
 		if (!this.program) {
 			this.onStatus?.({
@@ -817,6 +873,7 @@ var PinLayer = class {
 	}
 	rebuild() {
 		if (!this.ready) return;
+		this.sortDirty = true;
 		if (!this.dirty) {
 			const previousPending = new Set(this.pendingElevation);
 			const center = {
@@ -833,8 +890,10 @@ var PinLayer = class {
 					this.dirty = true;
 					break;
 				}
+				const patch = new Float32Array(data);
+				this.instanceData.set(patch, slice.offset);
 				this.gl.bindBuffer(this.gl.ARRAY_BUFFER, this.buffer);
-				this.gl.bufferSubData(this.gl.ARRAY_BUFFER, slice.offset * Float32Array.BYTES_PER_ELEMENT, new Float32Array(data));
+				this.gl.bufferSubData(this.gl.ARRAY_BUFFER, this.gpuOffsets[i] * Float32Array.BYTES_PER_ELEMENT, patch);
 			}
 			if (!this.dirty) {
 				this.changedPins.clear();
@@ -874,7 +933,11 @@ var PinLayer = class {
 		});
 		this.ranges = ranges;
 		gl.bindBuffer(gl.ARRAY_BUFFER, this.buffer);
-		gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(data), gl.DYNAMIC_DRAW);
+		this.instanceData = new Float32Array(data);
+		this.paintOrder = this.pins.map((_, i) => i);
+		this.gpuOffsets = this.slices.map((slice) => slice.offset);
+		this.depths = new Float64Array(this.pins.length);
+		gl.bufferData(gl.ARRAY_BUFFER, this.instanceData, gl.DYNAMIC_DRAW);
 		this.dirty = false;
 		this.changedPins.clear();
 	}
@@ -893,8 +956,52 @@ var PinLayer = class {
 		if (this.status.status !== "supported") return;
 		this.frame = input;
 		this.projection.update(input, this.origin, this.map.getCenter(), 512 * 2 ** this.map.getZoom(), this.map.getProjection()?.type === "globe");
+		this.updatePaintOrder();
 		this.draw(context, false);
 	}
+	/** Reorder existing instances only when camera/data changes, preserving atlas batches. */
+	updatePaintOrder() {
+		const sorted = this.depthSorted;
+		let changed = this.sortDirty;
+		if (sorted) {
+			if (cacheChanged(this.sortMatrix, this.matrix)) changed = true;
+			if (cacheChanged(this.sortGlobeMatrix, this.projection.globeMatrix)) changed = true;
+			if (this.sortTransition !== this.projection.transition) changed = true;
+			if (this.sortWorld !== this.projection.world) changed = true;
+			this.sortTransition = this.projection.transition;
+			this.sortWorld = this.projection.world;
+		}
+		if (!changed) return;
+		this.sortDirty = false;
+		if (sorted) for (let i = 0; i < this.pins.length; i++) {
+			const offset = this.slices[i].offset;
+			const data = this.instanceData;
+			const depth = this.projection.depth(data[offset] * this.projection.world, data[offset + 1] * this.projection.world, this.elevations[i]);
+			this.depths[i] = Number.isFinite(depth) ? depth : -Infinity;
+		}
+		const compare = this.comparePaintOrder;
+		let ordered = true;
+		for (let i = 1; i < this.paintOrder.length; i++) if (compare(this.paintOrder[i - 1], this.paintOrder[i]) > 0) {
+			ordered = false;
+			break;
+		}
+		if (ordered) return;
+		this.paintOrder.sort(compare);
+		if (this.sortedData.length !== this.instanceData.length) this.sortedData = new Float32Array(this.instanceData.length);
+		const ranges = [];
+		let offset = 0;
+		for (const i of this.paintOrder) {
+			const slice = this.slices[i];
+			this.sortedData.set(this.instanceData.subarray(slice.offset, slice.offset + slice.length), offset);
+			this.gpuOffsets[i] = offset;
+			const count = slice.length / STRIDE;
+			if (count) pushRange(ranges, slice.page, offset / STRIDE, count);
+			offset += slice.length;
+		}
+		this.ranges = ranges;
+		this.gl.bindBuffer(this.gl.ARRAY_BUFFER, this.buffer);
+		this.gl.bufferSubData(this.gl.ARRAY_BUFFER, 0, this.sortedData);
+	}
 	draw(gl, pick) {
 		const u = this.uniforms ?? this.resolveUniforms(gl);
 		gl.useProgram(this.program);
@@ -985,7 +1092,10 @@ var PinLayer = class {
 		const pixels = new Uint8Array(rw * rh * 4);
 		gl.readPixels(x, y, rw, rh, gl.RGBA, gl.UNSIGNED_BYTE, pixels);
 		let id = 0;
-		for (let i = 0; i < pixels.length; i += 4) id = Math.max(id, pixels[i] + pixels[i + 1] * 256 + pixels[i + 2] * 65536);
+		for (let i = 0; i < pixels.length; i += 4) {
+			const candidate = pixels[i] + pixels[i + 1] * 256 + pixels[i + 2] * 65536;
+			if (candidate && (!id || this.gpuOffsets[candidate - 1] > this.gpuOffsets[id - 1])) id = candidate;
+		}
 		gl.disable(gl.SCISSOR_TEST);
 		gl.bindFramebuffer(gl.FRAMEBUFFER, previous);
 		this.map.painter.context.setDirty();
@@ -1195,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;
@@ -1805,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);
@@ -1822,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,
@@ -1862,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,
@@ -1897,8 +2067,14 @@ var MapLibreAdapter = class extends BaseMapAdapter {
 		if (this.map.getSource(handle.sourceId)) this.map.removeSource(handle.sourceId);
 	}
 	applyFeatureGroups(layerId, input) {
+		const depthSorted = input.find((group) => group.pin)?.pin.presentation.depthSort ?? false;
+		const sortedPins = [];
 		const groups = [];
 		for (const group of input) if (group.pin && this.getPinPresentationCapability().status !== "unsupported") {
+			if (depthSorted) {
+				sortedPins.push(group.pin);
+				continue;
+			}
 			const previous = groups[groups.length - 1];
 			if (previous?.pinBatch) previous.pinBatch.push(group.pin);
 			else groups.push({
@@ -1911,6 +2087,12 @@ var MapLibreAdapter = class extends BaseMapAdapter {
 			...group,
 			id: `ordinary:${group.id}`
 		});
+		if (sortedPins.length) groups.push({
+			id: "pin-depth-sorted",
+			features: [],
+			iconResources: [],
+			pinBatch: sortedPins
+		});
 		const handle = this.layers.get(layerId);
 		if (!handle) return;
 		const allPins = groups.flatMap((group) => group.pinBatch ?? []);
@@ -1940,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);
 				}
@@ -2114,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,
@@ -2210,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) {
@@ -2467,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.4.4",
+  "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.9.2"
+    "@orbat-mapper/tactical-draw": "^0.10.1"
   },
   "peerDependencies": {
     "maplibre-gl": ">=5.8.0 <7.0.0"