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

package/dist/index.d.mts

@@ -39,7 +39,11 @@ declare class PinResources {
   private invalidateDepth;
   private restore;
   constructor(map: Map$1);
-  setRoster(pins: readonly PinRender[]): void;
+  /**
+   * `pixelRatio` is the device pixels per CSS pixel the atlas is rasterized
+   * at; it is part of the roster key, so a change rebuilds the atlas.
+   */
+  setRoster(pins: readonly PinRender[], pixelRatio?: number): void;
   load(gl: WebGL2RenderingContext): Promise<PinResourceSnapshot | undefined>;
   dispose(): void;
 }
@@ -143,6 +147,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;
@@ -155,6 +166,8 @@ interface MapLibreLayerHandle {
    * skip calling it at all rather than pay for that every drag frame.
    */
   lastPinBatch?: readonly PinRender[];
+  /** The pixel ratio passed alongside `lastPinBatch`. */
+  lastPinPixelRatio?: number;
 }
 type PaintChannel = "fill" | "fill-pattern" | "line" | "circle" | "icon" | "text";
 interface MapLibreGroupBundle {
@@ -214,13 +227,41 @@ 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;
+  /**
+   * Device pixels per CSS pixel at which pin symbols are rasterized into their
+   * texture atlas. Defaults to the map's pixel ratio capped at 2, which bounds
+   * texture memory on dense screens. Set it (e.g. to the map's `pixelRatio`)
+   * for offscreen renders above 2× so pins stay as sharp as the output.
+   */
+  pinPixelRatio?: number;
 }
 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 pinPixelRatio?;
+  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 +275,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

@@ -81,11 +81,15 @@ var PinResources = class {
 		map.on("webglcontextrestored", this.restore);
 		map.on("move", this.invalidateDepth);
 	}
-	setRoster(pins) {
+	/**
+	* `pixelRatio` is the device pixels per CSS pixel the atlas is rasterized
+	* at; it is part of the roster key, so a change rebuilds the atlas.
+	*/
+	setRoster(pins, pixelRatio = 1) {
 		this.needsDepth = pins.some((pin) => pin.presentation.occlusion === "terrain");
 		const resources = /* @__PURE__ */ new Map();
 		for (const pin of pins) {
-			const scale = pin.presentation.sizePixels / pin.octagonSize * Math.min(devicePixelRatio, 2);
+			const scale = pin.presentation.sizePixels / pin.octagonSize * pixelRatio;
 			if (scale > (resources.get(pin.resource.id)?.scale ?? 0)) resources.set(pin.resource.id, {
 				pin,
 				scale
@@ -239,14 +243,15 @@ void main() {
   else if(kind < 1.5) {
     vec2 delta = tp-gp; float len = length(delta);
     vec2 dir = len > .0001 ? delta/len : vec2(0,1);
-    vec2 p = mix(gp,tp,c.y) + vec2(-dir.y,dir.x) * (c.x-.5)*a_shape.x;
+    // Widen by 1px so the fragment edge fade has room to run.
+    vec2 p = mix(gp,tp,c.y) + vec2(-dir.y,dir.x) * (c.x-.5)*(a_shape.x+1.);
     clip = vec4(p/u_view*2., mix(ground.z/ground.w,target.z/target.w,c.y), 1.);
     offset = vec2(0);
   } else { offset = (c - vec2(.5,0)) * a_shape.xy + a_shape.zw; }
   clip.xy += offset * 2. / u_view * clip.w;
   if (ground.w <= 0. || target.w <= 0.) clip = vec4(2,2,2,1);
   gl_Position=clip;
-  v_local=(c-.5)*a_shape.xy;
+  v_local=(c-.5)*(a_shape.xy + (kind > .5 && kind < 1.5 ? vec2(1,0) : vec2(0)));
   v_uv=mix(a_uv.xy,a_uv.zw,vec2(c.x,1.-c.y));
   v_bounds=a_uv; v_color=a_color; v_shape=a_shape; v_flags=a_flags; v_radius=a_target.w;
 }`;
@@ -288,6 +293,10 @@ void main() {
   if(kind < .5) {
     float edge=length(v_local)-v_shape.x*.5;
     paint.a *= 1.-smoothstep(-1.,0.,edge);
+  } else if(kind < 1.5) {
+    // World-mode stems lean with perspective; fade the long edges over one device pixel.
+    float aa=max(fwidth(v_local.x),1e-4);
+    paint.a *= clamp((v_shape.x*.5-abs(v_local.x))/aa+.5,0.,1.);
   } else if(kind > 4.5) {
     // One optional halo instance; reuse the canonical atlas, including text and HQ staff.
     vec2 size = v_shape.xy - vec2(2. * v_radius);
@@ -1305,13 +1314,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 +1955,40 @@ var MapLibreAdapter = class extends BaseMapAdapter {
 	viewChangeMode;
 	pendingIconImages = /* @__PURE__ */ new Set();
 	scalesGroundPointSymbolsNatively = true;
+	terrainActive = false;
+	terrainBanding;
+	pinPixelRatio;
+	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.pinPixelRatio = options.pinPixelRatio;
+		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 +2002,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 +2042,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,
@@ -2038,10 +2109,12 @@ var MapLibreAdapter = class extends BaseMapAdapter {
 		const allPins = groups.flatMap((group) => group.pinBatch ?? []);
 		if (allPins.length) {
 			handle.pinResources ??= new PinResources(this.map);
+			const pixelRatio = this.pinPixelRatio ?? Math.min(this.map.getPixelRatio(), 2);
 			const previousBatch = handle.lastPinBatch;
-			if (!(previousBatch !== void 0 && previousBatch.length === allPins.length && allPins.every((pin, index) => pin === previousBatch[index]))) {
-				handle.pinResources.setRoster(allPins);
+			if (!(previousBatch !== void 0 && handle.lastPinPixelRatio === pixelRatio && previousBatch.length === allPins.length && allPins.every((pin, index) => pin === previousBatch[index]))) {
+				handle.pinResources.setRoster(allPins, pixelRatio);
 				handle.lastPinBatch = allPins;
+				handle.lastPinPixelRatio = pixelRatio;
 			}
 		}
 		const desiredGroupIds = new Set(groups.map((group) => group.id));
@@ -2062,7 +2135,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 +2309,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 +2405,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 +2683,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.7.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"