@orbat-mapper/tactical-draw-adapter-maplibre 0.3.22 → 0.4.0

package/dist/index.mjs

@@ -1,5 +1,1035 @@
-import { BaseMapAdapter, DEFAULT_TEXT_SIZE_MAX_PIXELS, DEFAULT_TEXT_SIZE_MIN_PIXELS, HATCH_PATTERNS, PointerCallbackHub, TEXT_HALO_COLOR, TOUCH_HIT_TOLERANCE_PX, bindAbortable, evaluatePickCandidates, fillPatternImageId, makeFillPatternImage, mergeNativeAndCachedPickFeatures, nearestWorldCopyLng, pickHitTolerance, pickPointerType, resolveTextHaloWidth } from "@orbat-mapper/tactical-draw";
-import { project, unproject } from "@orbat-mapper/control-measures";
+import * as maplibregl from "maplibre-gl";
+import { LngLat, MercatorCoordinate } from "maplibre-gl";
+import { BaseMapAdapter, DEFAULT_TEXT_SIZE_MAX_PIXELS, DEFAULT_TEXT_SIZE_MIN_PIXELS, HATCH_PATTERNS, PointerCallbackHub, TEXT_HALO_COLOR, TOUCH_HIT_TOLERANCE_PX, bindAbortable, evaluatePickCandidates, fillPatternImageId, makeFillPatternImage, mergeNativeAndCachedPickFeatures, nearestWorldCopyLng, parseColor, pickHitTolerance, pickPointerType, resolveTextHaloWidth } from "@orbat-mapper/tactical-draw";
+import { EARTH_RADIUS, project, unproject } from "@orbat-mapper/control-measures";
+//#region src/pin-atlas.ts
+/**
+* Rasterize one icon's SVG. Kept separate from packing so a whole roster can
+* decode in parallel — shelf placement stays order-dependent, decoding is not.
+*/
+async function decodeIcon(resource) {
+	const image = new Image();
+	image.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(resource.svg)}`;
+	await image.decode();
+	return image;
+}
+/** Paged shelves avoid one texture per symbol and do not reorder draw instances. */
+var PinAtlas = class {
+	size;
+	entries = /* @__PURE__ */ new Map();
+	pages = [];
+	x = 0;
+	y = 0;
+	rowHeight = 0;
+	constructor(size = 2048) {
+		this.size = size;
+	}
+	add(resource, scale, image) {
+		if (this.entries.has(resource.id)) return;
+		const width = Math.min(this.size - 4, Math.max(1, Math.ceil(resource.width * scale)));
+		const height = Math.min(this.size - 4, Math.max(1, Math.ceil(resource.height * scale)));
+		if (this.x + width + 4 > this.size) {
+			this.x = 0;
+			this.y += this.rowHeight;
+			this.rowHeight = 0;
+		}
+		if (!this.pages.length || this.y + height + 4 > this.size) {
+			const canvas = document.createElement("canvas");
+			canvas.width = canvas.height = this.size;
+			this.pages.push(canvas);
+			this.x = this.y = this.rowHeight = 0;
+		}
+		const canvas = this.pages[this.pages.length - 1];
+		const x = this.x + 2, y = this.y + 2;
+		canvas.getContext("2d").drawImage(image, x, y, width, height);
+		this.entries.set(resource.id, {
+			page: this.pages.length - 1,
+			uv: [
+				x / this.size,
+				y / this.size,
+				(x + width) / this.size,
+				(y + height) / this.size
+			]
+		});
+		this.x += width + 4;
+		this.rowHeight = Math.max(this.rowHeight, height + 4);
+	}
+};
+//#endregion
+//#region src/pin-resources.ts
+/** One atlas roster per logical layer, shared across ordinary-graphic barriers. */
+var PinResources = class {
+	map;
+	revision = 0;
+	key = "";
+	resources = /* @__PURE__ */ new Map();
+	pending;
+	textures = [];
+	context;
+	disposed = false;
+	needsDepth = false;
+	invalidateDepth = () => {
+		if (this.needsDepth && this.map.getTerrain() && this.map.getProjection()?.type === "globe") this.map.painter.terrainFacilitator.depthDirty = true;
+	};
+	restore = () => {
+		this.revision++;
+		this.pending = void 0;
+		this.textures = [];
+	};
+	constructor(map) {
+		this.map = map;
+		map.on("webglcontextrestored", this.restore);
+		map.on("move", this.invalidateDepth);
+	}
+	setRoster(pins) {
+		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);
+			if (scale > (resources.get(pin.resource.id)?.scale ?? 0)) resources.set(pin.resource.id, {
+				pin,
+				scale
+			});
+		}
+		const key = JSON.stringify([...resources].map(([id, value]) => [id, value.scale]).sort(([a], [b]) => a.localeCompare(b)));
+		if (key === this.key) return;
+		this.key = key;
+		this.resources = resources;
+		this.revision++;
+		this.pending = void 0;
+	}
+	load(gl) {
+		this.context = gl;
+		return this.pending ??= (async () => {
+			const revision = this.revision;
+			const sizes = [...this.resources.values()].map(({ pin, scale }) => ({
+				w: pin.resource.width * scale + 4,
+				h: pin.resource.height * scale + 4
+			}));
+			const area = sizes.reduce((sum, s) => sum + s.w * s.h, 0);
+			const side = Math.max(256, Math.sqrt(area) * 1.3, ...sizes.flatMap((s) => [s.w, s.h]));
+			const atlas = new PinAtlas(Math.min(2048, gl.getParameter(gl.MAX_TEXTURE_SIZE), 2 ** Math.ceil(Math.log2(side))));
+			const icons = [...this.resources.values()];
+			const images = await Promise.all(icons.map(({ pin }) => decodeIcon(pin.resource)));
+			if (this.disposed || revision !== this.revision) return;
+			icons.forEach(({ pin, scale }, i) => atlas.add(pin.resource, scale, images[i]));
+			const textures = [];
+			try {
+				for (const page of atlas.pages) {
+					const texture = gl.createTexture();
+					if (!texture) throw new Error("Could not allocate pin texture");
+					textures.push(texture);
+					gl.activeTexture(gl.TEXTURE0);
+					gl.bindTexture(gl.TEXTURE_2D, texture);
+					gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+					gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+					gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, page);
+					gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+					gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+					gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+					gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+				}
+			} catch (error) {
+				for (const texture of textures) gl.deleteTexture(texture);
+				throw error;
+			}
+			for (const texture of this.textures) gl.deleteTexture(texture);
+			this.textures = textures;
+			this.map.painter.context.setDirty();
+			return {
+				atlas,
+				textures
+			};
+		})();
+	}
+	dispose() {
+		this.disposed = true;
+		this.revision++;
+		this.map.off("webglcontextrestored", this.restore);
+		this.map.off("move", this.invalidateDepth);
+		for (const texture of this.textures) this.context?.deleteTexture(texture);
+		this.textures = [];
+		this.resources.clear();
+		this.pending = void 0;
+	}
+};
+//#endregion
+//#region src/pin-inversion.ts
+/** Follow the local projection branch from the unit, never a foreground terrain ray hit. */
+function invertPinProjection(project, initial, target, latitudeLimit = 85.051129) {
+	let position = [initial[0], initial[1]];
+	const valid = (p) => p.every(Number.isFinite) && Math.abs(p[1]) < latitudeLimit;
+	if (!valid(position) || !target.every(Number.isFinite)) return null;
+	for (let n = 0; n < 12; n++) {
+		const a = project(position), ex = target[0] - a[0], ey = target[1] - a[1], error = Math.hypot(ex, ey);
+		if (!Number.isFinite(error)) return null;
+		if (error < .05) return position;
+		const step = 1e-5, b = project([position[0] + step, position[1]]), c = project([position[0], position[1] + step]);
+		const jx = (b[0] - a[0]) / step, jy = (b[1] - a[1]) / step, kx = (c[0] - a[0]) / step, ky = (c[1] - a[1]) / step, det = jx * ky - jy * kx;
+		if (!Number.isFinite(det) || Math.abs(det) < 1e-12) return null;
+		const dx = (ex * ky - ey * kx) / det, dy = (ey * jx - ex * jy) / det;
+		let improved = false;
+		for (let damping = 1; damping >= 1 / 128; damping /= 2) {
+			const candidate = [position[0] + dx * damping, position[1] + dy * damping];
+			if (!valid(candidate)) continue;
+			const pixel = project(candidate);
+			if (Math.hypot(target[0] - pixel[0], target[1] - pixel[1]) < error) {
+				position = candidate;
+				improved = true;
+				break;
+			}
+		}
+		if (!improved) return null;
+	}
+	return null;
+}
+//#endregion
+//#region src/pin-shaders.ts
+const PIN_VERTEX = `#version 300 es
+precision highp float;
+layout(location=0) in vec4 a_ground;
+layout(location=1) in vec4 a_target;
+layout(location=2) in vec4 a_shape;
+layout(location=3) in vec4 a_color;
+layout(location=4) in vec4 a_uv;
+layout(location=5) in vec4 a_flags;
+uniform mat4 u_matrix;
+uniform float u_world;
+uniform mat4 u_globeMatrix;
+uniform vec4 u_clippingPlane;
+uniform vec2 u_origin;
+uniform float u_globeTransition;
+out float v_horizon;
+vec4 projectPin(vec3 position, out float horizon) {
+  vec4 flatClip = u_matrix * vec4(position.xy * u_world, position.z, 1.);
+  horizon = 1.;
+  if(u_globeTransition == 0.) return flatClip;
+  vec2 mercator = position.xy + u_origin;
+  float angle = mercator.x * 6.283185307179586 + 3.141592653589793;
+  float t = exp(3.141592653589793 - mercator.y * 6.283185307179586);
+  vec3 sphere = vec3(sin(angle)*2.*t, t*t-1., cos(angle)*2.*t)/(t*t+1.);
+  sphere *= 1. + position.z / 6371008.8;
+  vec4 globe = u_globeMatrix * vec4(sphere, 1.);
+  float distance = dot(sphere,u_clippingPlane.xyz) + u_clippingPlane.w;
+  horizon = 1. - (1.-distance) * max(0.,(u_globeTransition-.2)/.8);
+  return mix(flatClip,globe,u_globeTransition);
+}
+uniform vec2 u_view;
+out vec2 v_local;
+out vec2 v_uv;
+flat out vec4 v_bounds;
+flat out vec4 v_color;
+flat out vec4 v_shape;
+flat out vec4 v_flags;
+flat out float v_radius;
+const vec2 corners[6] = vec2[6](vec2(0,0),vec2(1,0),vec2(0,1),vec2(0,1),vec2(1,0),vec2(1,1));
+void main() {
+  vec2 c = corners[gl_VertexID];
+  float groundHorizon, targetHorizon;
+  vec4 ground = projectPin(a_ground.xyz, groundHorizon);
+  vec4 target = projectPin(a_target.xyz, targetHorizon);
+  if(a_flags.y < .5) { target = ground; targetHorizon = groundHorizon; target.y += a_ground.w * 2. / u_view.y * target.w; }
+  v_horizon = a_flags.x < .5 ? groundHorizon : (a_flags.x < 1.5 ? mix(groundHorizon,targetHorizon,c.y) : targetHorizon);
+  vec2 gp = ground.xy / ground.w * u_view * .5;
+  vec2 tp = target.xy / target.w * u_view * .5;
+  float kind = a_flags.x;
+  vec4 clip = target;
+  vec2 offset;
+  if(kind < .5) { clip = ground; offset = (c - .5) * a_shape.xy; }
+  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;
+    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_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;
+}`;
+const PIN_FRAGMENT = `#version 300 es
+precision highp float;
+in float v_horizon;
+in vec2 v_local;
+in vec2 v_uv;
+flat in vec4 v_bounds;
+flat in vec4 v_color;
+flat in vec4 v_shape;
+flat in vec4 v_flags;
+flat in float v_radius;
+uniform sampler2D u_atlas;
+// Texture return precision follows the sampler, not the default float precision.
+// Preserve the packed depth channels on GPUs that implement lowp separately.
+uniform highp sampler2D u_terrain;
+uniform vec2 u_buffer;
+uniform bool u_hasTerrain;
+uniform bool u_pick;
+
+out vec4 color;
+float symbolAlpha(vec2 pixel, vec2 size) {
+  vec2 uv = pixel / size + .5;
+  if(any(lessThan(uv,vec2(0))) || any(greaterThan(uv,vec2(1)))) return 0.;
+  return texture(u_atlas,mix(v_bounds.xy,v_bounds.zw,vec2(uv.x,1.-uv.y))).a;
+}
+void main() {
+  if(v_horizon < 0.) discard;
+  if(u_hasTerrain && v_flags.z > .5) {
+    vec4 packed=texture(u_terrain,gl_FragCoord.xy/u_buffer);
+    float depth=dot(packed,vec4(1./16777216.,1./65536.,1./256.,1.));
+    float ours=gl_FragCoord.z*2.-1.;
+    // A transparent depth texel is sky (no terrain), not a near-plane occluder.
+    if(depth > 0. && ours > depth + .00012) discard;
+  }
+  vec4 paint=v_color;
+  float kind=v_flags.x;
+  if(kind < .5) {
+    float edge=length(v_local)-v_shape.x*.5;
+    paint.a *= 1.-smoothstep(-1.,0.,edge);
+  } 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);
+    float alpha = symbolAlpha(v_local,size);
+    for(int i=0;i<16;i++) {
+      float angle = float(i) * 6.28318530718 / 16.;
+      vec2 direction = vec2(cos(angle),sin(angle));
+      alpha = max(alpha,symbolAlpha(v_local + direction * v_radius,size));
+      alpha = max(alpha,symbolAlpha(v_local + direction * v_radius * .5,size));
+    }
+    paint.a *= alpha;
+  } else if(kind > 3.5) {
+    if(min(v_shape.x*.5-abs(v_local.x),v_shape.y*.5-abs(v_local.y)) > 2.) discard;
+  } else if(kind > 2.5) {
+    paint *= texture(u_atlas,v_uv);
+  } else if(kind > 1.5) {
+    float radius=min(v_radius,min(v_shape.x,v_shape.y)*.5);
+    vec2 q=abs(v_local)-v_shape.xy*.5+radius;
+    float edge=length(max(q,0.))+min(max(q.x,q.y),0.)-radius;
+    paint.a *= 1.-smoothstep(-1.,0.,edge);
+  }
+  if(paint.a < .01) discard;
+  if(u_pick) {
+    float id=v_flags.w;
+    color=vec4(mod(id,256.),mod(floor(id/256.),256.),floor(id/65536.),255.)/255.;
+  } else color=vec4(paint.rgb*paint.a,paint.a);
+}`;
+//#endregion
+//#region src/pin-projection.ts
+/**
+* Single source of truth for the globe radius the pin pipeline works in. The
+* GLSL in `pin-shaders.ts` repeats the literal because a shader cannot import;
+* this export is what it must stay in step with.
+*/
+const PIN_GLOBE_RADIUS = EARTH_RADIUS;
+/** Mercator is singular at the poles; this sub-metre inset keeps GPU inputs finite. */
+function pinMercator(position) {
+	return MercatorCoordinate.fromLngLat([position[0], Math.max(-89.999999, Math.min(89.999999, position[1]))]);
+}
+const multiply = (m, v) => [
+	0,
+	1,
+	2,
+	3
+].map((row) => v.reduce((sum, n, col) => sum + n * m[col * 4 + row], 0));
+/** CPU counterpart of projectPin in pin-shaders.ts, also used by drag inversion. */
+var PinProjection = class {
+	matrix = new Float32Array(16);
+	globeMatrix = new Float32Array(16);
+	clippingPlane = new Float32Array(4);
+	transition = 0;
+	origin = [0, 0];
+	world = 512;
+	update(input, origin, center, world, globe) {
+		this.origin = origin;
+		this.world = world;
+		const data = globe ? input.getProjectionData({
+			tileID: { canonical: {
+				x: 0,
+				y: 0,
+				z: 0
+			} },
+			applyGlobeMatrix: true
+		}) : void 0;
+		this.transition = data?.projectionTransition ?? 0;
+		if (data) {
+			this.globeMatrix.set(data.mainMatrix);
+			this.clippingPlane.set(data.clippingPlane);
+		}
+		const fallback = globe ? input.defaultProjectionData.fallbackMatrix : input.modelViewProjectionMatrix;
+		const xyScale = globe ? 1 / world : 1;
+		const zScale = globe ? MercatorCoordinate.fromLngLat(center).meterInMercatorCoordinateUnits() : 1;
+		for (let row = 0; row < 4; row++) {
+			this.matrix[row] = fallback[row] * xyScale;
+			this.matrix[4 + row] = fallback[4 + row] * xyScale;
+			this.matrix[8 + row] = fallback[8 + row] * zScale;
+			this.matrix[12 + row] = fallback[12 + row] + fallback[row] * xyScale * origin[0] * world + fallback[4 + row] * xyScale * origin[1] * world;
+		}
+	}
+	project(worldX, worldY, elevation) {
+		const flat = multiply(this.matrix, [
+			worldX,
+			worldY,
+			elevation,
+			1
+		]);
+		if (this.transition === 0) return {
+			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 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 {
+			clip: flat.map((n, i) => n * (1 - this.transition) + globe[i] * this.transition),
+			horizon
+		};
+	}
+};
+//#endregion
+//#region src/pin-kind.ts
+/**
+* Draw-kind tags shared between the pin instance data (pin-layer.ts) and the
+* WebGL shaders (pin-shaders.ts).
+*
+* The GLSL side branches on numeric thresholds (`kind < .5`, `kind < 1.5`,
+* `kind > 4.5`, ...) rather than importing this module — see the comment
+* near those branches in pin-shaders.ts. If you renumber a value here, you
+* must update the shader thresholds by hand or the two will silently drift.
+*/
+const PIN_KIND = {
+	DOT: 0,
+	STEM: 1,
+	PLATE: 2,
+	SYMBOL: 3,
+	HIGHLIGHT: 4,
+	SYMBOL_HALO: 5
+};
+//#endregion
+//#region src/pin-layer.ts
+const STRIDE = 24;
+/** Shader-ready `[r, g, b, a]` in 0-1, with the color's own alpha folded into `opacity`. */
+function rgba(color, opacity) {
+	const { r, g, b, a } = parseColor(color);
+	return [
+		r / 255,
+		g / 255,
+		b / 255,
+		a * opacity
+	];
+}
+function shader(gl, type, source) {
+	const s = gl.createShader(type);
+	gl.shaderSource(s, source);
+	gl.compileShader(s);
+	if (!gl.getShaderParameter(s, gl.COMPILE_STATUS)) {
+		const message = gl.getShaderInfoLog(s);
+		gl.deleteShader(s);
+		throw new Error(`Pin shader: ${message}`);
+	}
+	return s;
+}
+/**
+* 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;
+	const previous = ranges[ranges.length - 1];
+	if (previous?.page === image.page) previous.count++;
+	else ranges.push({
+		page: image.page,
+		first,
+		count: 1
+	});
+	data.push(...a, ...target, ...shape, ...color, ...image.uv, kind, mode, occlusionTerrain, instanceId);
+}
+/**
+* Ground-following point along a direction-arrow segment, `t` of the way from `from`
+* to `to` (both east/north metre offsets from the pin). Hoisted out of rebuild()'s
+* per-pin, per-segment loops — at 10k pins that loop can define this closure 240k+
+* times per rebuild otherwise.
+*/
+function arrowSegmentPoint(center, position, elevationAt, from, to, t) {
+	const east = from[0] + (to[0] - from[0]) * t;
+	const north = from[1] + (to[1] - from[1]) * t;
+	const ll = [position[0] + east / (111320 * Math.cos(position[1] * Math.PI / 180)), position[1] + north / 111320];
+	const mc = pinMercator(ll);
+	mc.x += Math.round(center.x - mc.x);
+	return [
+		mc.x - center.x,
+		mc.y - center.y,
+		elevationAt(ll) + 1,
+		0
+	];
+}
+/** Batched GPU pin rendering. Adjacent groups only; instance order is paint order. */
+var PinLayer = class {
+	id;
+	resources;
+	onStatus;
+	type = "custom";
+	renderingMode = "2d";
+	map;
+	gl;
+	program;
+	uniforms;
+	buffer;
+	vao;
+	textures = [];
+	atlas = new PinAtlas();
+	pins = [];
+	ranges = [];
+	version = 0;
+	resourceRevision = -1;
+	needsDepth = false;
+	elevationCache = /* @__PURE__ */ new Map();
+	pendingElevation = /* @__PURE__ */ new Set();
+	removed = false;
+	ready = false;
+	dirty = true;
+	changedPins = /* @__PURE__ */ new Set();
+	slices = [];
+	origin = [0, 0];
+	elevations = [];
+	projection = new PinProjection();
+	matrix = this.projection.matrix;
+	frame;
+	pickFramebuffer;
+	pickTexture;
+	pickSize = "";
+	status = { status: "supported" };
+	refreshTerrain = (event) => {
+		if (event.sourceId && event.sourceId !== this.map.getTerrain()?.source) return;
+		if (event.type === "sourcedata" || event.type === "terrain") this.elevationCache.clear();
+		this.dirty = true;
+		this.map.triggerRepaint();
+	};
+	elevation(position) {
+		if (!this.map.getTerrain() || Math.abs(position[1]) >= 85.051129) return 0;
+		const key = `${position[0]}/${position[1]}`;
+		const cached = this.elevationCache.get(key);
+		if (cached !== void 0) return cached;
+		const terrain = this.map.terrain;
+		const { tileID, mercatorX, mercatorY } = terrain._getOverscaledTileIDFromLngLatZoom(new LngLat(position[0], position[1]), Math.min(terrain.tileManager.maxzoom, terrain.tileManager.getSource().maxzoom + terrain.tileManager.deltaZoom));
+		const sampler = terrain._getElevationSampler(tileID);
+		if (!sampler) return NaN;
+		const value = sampler(mercatorX % 8192, mercatorY % 8192, 8192) * terrain.exaggeration;
+		this.elevationCache.set(key, value);
+		return value;
+	}
+	has(id) {
+		return this.pins.some((pin) => pin.id === id);
+	}
+	constructor(id, resources, onStatus) {
+		this.id = id;
+		this.resources = resources;
+		this.onStatus = onStatus;
+	}
+	restoreContext = () => {
+		this.ready = false;
+		this.resourceRevision = -1;
+		this.textures = [];
+		this.pickSize = "";
+		this.pickTexture = void 0;
+		this.pickFramebuffer = void 0;
+		this.onRemoveListeners();
+		this.onAdd(this.map, this.gl);
+		this.setPins(this.pins);
+	};
+	onRemoveListeners() {
+		this.map.off("sourcedata", this.refreshTerrain);
+		this.map.off("terrain", this.refreshTerrain);
+		this.map.off("resize", this.refreshTerrain);
+		this.map.off("moveend", this.refreshTerrain);
+		this.map.off("webglcontextrestored", this.restoreContext);
+	}
+	onAdd(map, context) {
+		this.removed = false;
+		this.map = map;
+		this.gl = context;
+		const gl = this.gl;
+		try {
+			const program = gl.createProgram();
+			for (const [type, source] of [[gl.VERTEX_SHADER, PIN_VERTEX], [gl.FRAGMENT_SHADER, PIN_FRAGMENT]]) {
+				const s = shader(gl, type, source);
+				gl.attachShader(program, s);
+				gl.deleteShader(s);
+			}
+			gl.linkProgram(program);
+			if (!gl.getProgramParameter(program, gl.LINK_STATUS)) throw new Error(gl.getProgramInfoLog(program) ?? "Pin link failed");
+			this.program = program;
+			this.uniforms = this.resolveUniforms(gl);
+			this.buffer = gl.createBuffer();
+			this.vao = gl.createVertexArray();
+			map.on("webglcontextrestored", this.restoreContext);
+			map.on("sourcedata", this.refreshTerrain);
+			map.on("terrain", this.refreshTerrain);
+			map.on("resize", this.refreshTerrain);
+			map.on("moveend", this.refreshTerrain);
+		} catch (error) {
+			this.setStatus({
+				status: "unavailable",
+				reason: String(error)
+			});
+		}
+	}
+	/** Uniform locations are fixed once a program is linked; resolved here, not per draw. */
+	resolveUniforms(gl) {
+		const program = this.program;
+		const uniforms = {
+			matrix: gl.getUniformLocation(program, "u_matrix"),
+			globeMatrix: gl.getUniformLocation(program, "u_globeMatrix"),
+			clippingPlane: gl.getUniformLocation(program, "u_clippingPlane"),
+			origin: gl.getUniformLocation(program, "u_origin"),
+			globeTransition: gl.getUniformLocation(program, "u_globeTransition"),
+			world: gl.getUniformLocation(program, "u_world"),
+			view: gl.getUniformLocation(program, "u_view"),
+			buffer: gl.getUniformLocation(program, "u_buffer"),
+			pick: gl.getUniformLocation(program, "u_pick"),
+			atlas: gl.getUniformLocation(program, "u_atlas"),
+			terrain: gl.getUniformLocation(program, "u_terrain"),
+			hasTerrain: gl.getUniformLocation(program, "u_hasTerrain")
+		};
+		this.uniforms = uniforms;
+		return uniforms;
+	}
+	setStatus(status) {
+		if (status.status === this.status.status && status.reason === this.status.reason) return;
+		this.status = status;
+		this.onStatus?.({
+			...status,
+			graphicIds: this.pins.filter((p) => !p.highlightOnly).map((p) => p.id)
+		});
+	}
+	getStatus(id) {
+		return id && this.pendingElevation.has(id) ? { status: "waiting-for-elevation" } : { ...this.status };
+	}
+	async setPins(pins, changedIndices) {
+		if (pins.length !== this.pins.length) this.dirty = true;
+		else {
+			const changed = changedIndices ?? pins.flatMap((pin, i) => pin !== this.pins[i] ? [i] : []);
+			for (const i of changed) {
+				if (pins[i].id !== this.pins[i].id) this.dirty = true;
+				this.changedPins.add(i);
+			}
+		}
+		this.pins = pins;
+		if (this.elevationCache.size > pins.length * 60 + 1e3) this.elevationCache.clear();
+		if (!this.program) {
+			this.onStatus?.({
+				...this.status,
+				graphicIds: pins.map((pin) => pin.id)
+			});
+			return;
+		}
+		this.needsDepth = pins.some((p) => p.presentation.occlusion === "terrain");
+		if (this.resourceRevision === this.resources.revision && this.ready) {
+			this.map.triggerRepaint();
+			return;
+		}
+		this.dirty = true;
+		this.resourceRevision = this.resources.revision;
+		this.ready = false;
+		this.setStatus({ status: "loading" });
+		const version = ++this.version;
+		try {
+			const snapshot = await this.resources.load(this.gl);
+			if (!snapshot || version !== this.version || this.removed) return;
+			this.atlas = snapshot.atlas;
+			this.textures = snapshot.textures;
+			this.ready = true;
+			this.map.triggerRepaint();
+		} catch (error) {
+			this.setStatus({
+				status: "unavailable",
+				reason: `Pin resources: ${error}`
+			});
+		}
+	}
+	buildPin(i, center, data, ranges) {
+		const pin = this.pins[i], p = pin.presentation;
+		const anchor = pinMercator(pin.position);
+		anchor.x += Math.round(center.x - anchor.x);
+		const elevation = this.elevation(pin.position);
+		this.elevations[i] = elevation;
+		if (!Number.isFinite(elevation)) {
+			this.pendingElevation.add(pin.id);
+			return;
+		}
+		this.pendingElevation.delete(pin.id);
+		const a = [
+			anchor.x - center.x,
+			anchor.y - center.y,
+			elevation,
+			p.liftPixels
+		];
+		const b = [
+			a[0],
+			a[1],
+			elevation + (p.mode === "world" ? p.heightMeters : 0),
+			p.plate.radius
+		];
+		const image = this.atlas.entries.get(pin.resource.id);
+		const opacity = pin.opacity;
+		const highlightOnly = pin.highlightOnly;
+		const instanceId = i + 1;
+		const occlusionFlag = p.occlusion === "terrain" ? 1 : 0;
+		const worldMode = p.mode === "world" ? 1 : 0;
+		const haloColor = rgba(p.halo.color, p.halo.opacity * opacity);
+		const stemColor = rgba(p.stem.color, p.stem.opacity * opacity);
+		if (pin.direction !== void 0 && !pin.highlightOnly) {
+			const elevationAt = (ll) => this.elevation(ll);
+			const angle = pin.direction, length = 180;
+			const tip = [Math.sin(angle) * length, Math.cos(angle) * length];
+			const paths = [
+				[[0, 0], tip],
+				[[tip[0] - Math.sin(angle - .5) * length * .25, tip[1] - Math.cos(angle - .5) * length * .25], tip],
+				[[tip[0] - Math.sin(angle + .5) * length * .25, tip[1] - Math.cos(angle + .5) * length * .25], tip]
+			];
+			const saved = [...a];
+			for (const [from, to] of paths) for (let segment = 0; segment < 8; segment++) {
+				const ground = arrowSegmentPoint(center, pin.position, elevationAt, from, to, segment / 8);
+				const target = arrowSegmentPoint(center, pin.position, elevationAt, from, to, (segment + 1) / 8);
+				if (!Number.isFinite(ground[2]) || !Number.isFinite(target[2])) continue;
+				a.splice(0, 4, ...ground);
+				appendPinInstance(data, ranges, image, highlightOnly, instanceId, occlusionFlag, PIN_KIND.STEM, [
+					p.stem.width + 2 * p.halo.width,
+					0,
+					0,
+					0
+				], haloColor, a, target, 1);
+				appendPinInstance(data, ranges, image, highlightOnly, instanceId, occlusionFlag, PIN_KIND.STEM, [
+					p.stem.width,
+					0,
+					0,
+					0
+				], stemColor, a, target, 1);
+			}
+			a.splice(0, 4, ...saved);
+		}
+		appendPinInstance(data, ranges, image, highlightOnly, instanceId, occlusionFlag, PIN_KIND.STEM, [
+			p.stem.width + 2 * p.halo.width,
+			0,
+			0,
+			0
+		], haloColor, a, b, worldMode);
+		appendPinInstance(data, ranges, image, highlightOnly, instanceId, occlusionFlag, PIN_KIND.STEM, [
+			p.stem.width,
+			0,
+			0,
+			0
+		], stemColor, a, b, worldMode);
+		appendPinInstance(data, ranges, image, highlightOnly, instanceId, occlusionFlag, PIN_KIND.DOT, [
+			2 * (p.dot.radius + p.halo.width),
+			2 * (p.dot.radius + p.halo.width),
+			0,
+			0
+		], haloColor, a, b, worldMode);
+		appendPinInstance(data, ranges, image, highlightOnly, instanceId, occlusionFlag, PIN_KIND.DOT, [
+			2 * p.dot.radius,
+			2 * p.dot.radius,
+			0,
+			0
+		], rgba(p.dot.color, p.dot.opacity * opacity), a, b, worldMode);
+		const scale = p.sizePixels / pin.octagonSize;
+		const width = pin.resource.width * scale, height = pin.resource.height * scale;
+		const offsetX = (pin.resource.width / 2 - pin.resource.anchor[0]) * scale;
+		const padding = p.plate.enabled ? p.plate.padding : 0;
+		if (p.plate.enabled) {
+			appendPinInstance(data, ranges, image, highlightOnly, instanceId, occlusionFlag, PIN_KIND.PLATE, [
+				width + padding * 2,
+				height + padding * 2,
+				offsetX,
+				0
+			], rgba(p.plate.borderColor, p.plate.opacity * opacity), a, b, worldMode);
+			appendPinInstance(data, ranges, image, highlightOnly, instanceId, occlusionFlag, PIN_KIND.PLATE, [
+				Math.max(0, width + padding * 2 - p.plate.borderWidth * 2),
+				Math.max(0, height + padding * 2 - p.plate.borderWidth * 2),
+				offsetX,
+				p.plate.borderWidth
+			], rgba(p.plate.color, p.plate.opacity * opacity), a, b, worldMode);
+		}
+		if (p.symbolHalo.width > 0 && p.symbolHalo.opacity > 0) {
+			const radius = p.symbolHalo.width;
+			appendPinInstance(data, ranges, image, highlightOnly, instanceId, occlusionFlag, PIN_KIND.SYMBOL_HALO, [
+				width + radius * 2,
+				height + radius * 2,
+				offsetX,
+				padding - radius
+			], rgba(p.symbolHalo.color, p.symbolHalo.opacity * opacity), a, [
+				b[0],
+				b[1],
+				b[2],
+				radius
+			], worldMode);
+		}
+		appendPinInstance(data, ranges, image, highlightOnly, instanceId, occlusionFlag, PIN_KIND.SYMBOL, [
+			width,
+			height,
+			offsetX,
+			padding
+		], [
+			1,
+			1,
+			1,
+			opacity
+		], a, b, worldMode);
+		if (pin.highlightOnly) {
+			const margin = Math.max(padding, p.symbolHalo.opacity > 0 ? p.symbolHalo.width : 0);
+			appendPinInstance(data, ranges, image, highlightOnly, instanceId, occlusionFlag, PIN_KIND.HIGHLIGHT, [
+				width + margin * 2 + 6,
+				height + margin * 2 + 6,
+				offsetX,
+				padding - margin - 3
+			], rgba("#0284c7", 1), a, b, worldMode);
+		}
+	}
+	rebuild() {
+		if (!this.ready) return;
+		if (!this.dirty) {
+			const previousPending = new Set(this.pendingElevation);
+			const center = {
+				x: this.origin[0],
+				y: this.origin[1]
+			};
+			for (const i of this.changedPins) {
+				const data = [];
+				this.buildPin(i, center, data, []);
+				const slice = this.slices[i];
+				const page = this.atlas.entries.get(this.pins[i].resource.id)?.page;
+				if (data.length !== slice.length || page !== slice.page) {
+					this.pendingElevation = previousPending;
+					this.dirty = true;
+					break;
+				}
+				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));
+			}
+			if (!this.dirty) {
+				this.changedPins.clear();
+				return;
+			}
+		}
+		const map = this.map, gl = this.gl;
+		if (!this.ready) return;
+		const viewCenter = map.getCenter();
+		const center = pinMercator([viewCenter.lng, viewCenter.lat]);
+		this.origin = [center.x, center.y];
+		const data = [];
+		const ranges = [];
+		this.elevations = [];
+		const previousPending = this.pendingElevation;
+		this.pendingElevation = /* @__PURE__ */ new Set();
+		this.setStatus({ status: "supported" });
+		this.slices = [];
+		for (let i = 0; i < this.pins.length; i++) {
+			const offset = data.length;
+			this.buildPin(i, center, data, ranges);
+			this.slices.push({
+				offset,
+				length: data.length - offset,
+				page: this.atlas.entries.get(this.pins[i].resource.id)?.page
+			});
+		}
+		const waiting = [...this.pendingElevation].filter((id) => !previousPending.has(id));
+		const available = [...previousPending].filter((id) => !this.pendingElevation.has(id));
+		if (waiting.length) this.onStatus?.({
+			status: "waiting-for-elevation",
+			graphicIds: waiting
+		});
+		if (available.length) this.onStatus?.({
+			status: "supported",
+			graphicIds: available
+		});
+		this.ranges = ranges;
+		gl.bindBuffer(gl.ARRAY_BUFFER, this.buffer);
+		gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(data), gl.DYNAMIC_DRAW);
+		this.dirty = false;
+		this.changedPins.clear();
+	}
+	render(context, input) {
+		if (!this.program || !this.ready || this.removed) return;
+		if (this.dirty || this.changedPins.size) try {
+			this.rebuild();
+		} catch (error) {
+			this.setStatus({
+				status: "unavailable",
+				reason: `Pin terrain: ${error}`
+			});
+			this.dirty = false;
+			return;
+		}
+		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.draw(context, false);
+	}
+	draw(gl, pick) {
+		const u = this.uniforms ?? this.resolveUniforms(gl);
+		gl.useProgram(this.program);
+		gl.bindVertexArray(this.vao);
+		gl.bindBuffer(gl.ARRAY_BUFFER, this.buffer);
+		gl.disable(gl.DEPTH_TEST);
+		gl.depthRange(0, 1);
+		gl.depthMask(false);
+		gl.disable(gl.CULL_FACE);
+		gl.disable(gl.STENCIL_TEST);
+		if (pick) gl.disable(gl.BLEND);
+		else {
+			gl.enable(gl.BLEND);
+			gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+		}
+		const width = this.map.getContainer().clientWidth, height = this.map.getContainer().clientHeight;
+		gl.uniformMatrix4fv(u.matrix, false, this.matrix);
+		gl.uniformMatrix4fv(u.globeMatrix, false, this.projection.globeMatrix);
+		gl.uniform4fv(u.clippingPlane, this.projection.clippingPlane);
+		gl.uniform2f(u.origin, this.origin[0], this.origin[1]);
+		gl.uniform1f(u.globeTransition, this.projection.transition);
+		gl.uniform1f(u.world, 512 * 2 ** this.map.getZoom());
+		gl.uniform2f(u.view, width, height);
+		gl.uniform2f(u.buffer, gl.drawingBufferWidth, gl.drawingBufferHeight);
+		gl.uniform1i(u.pick, pick ? 1 : 0);
+		gl.uniform1i(u.atlas, 0);
+		gl.uniform1i(u.terrain, 1);
+		const terrain = this.map.terrain;
+		const needsDepth = this.needsDepth && !!this.map.getTerrain();
+		const texture = needsDepth ? terrain?._fboDepthTexture?.texture : null;
+		if (needsDepth && !texture) {
+			this.setStatus({
+				status: "unavailable",
+				reason: "MapLibre terrain depth texture is unavailable"
+			});
+			this.dirty = true;
+			gl.bindVertexArray(null);
+			return;
+		}
+		gl.uniform1i(u.hasTerrain, texture ? 1 : 0);
+		gl.activeTexture(gl.TEXTURE1);
+		gl.bindTexture(gl.TEXTURE_2D, texture ?? this.textures[0]);
+		gl.activeTexture(gl.TEXTURE0);
+		for (const range of this.ranges) {
+			gl.bindTexture(gl.TEXTURE_2D, this.textures[range.page]);
+			for (let attr = 0; attr < 6; attr++) {
+				gl.enableVertexAttribArray(attr);
+				gl.vertexAttribPointer(attr, 4, gl.FLOAT, false, STRIDE * 4, (range.first * STRIDE + attr * 4) * 4);
+				gl.vertexAttribDivisor(attr, 1);
+			}
+			gl.drawArraysInstanced(gl.TRIANGLES, 0, 6, range.count);
+		}
+		gl.bindVertexArray(null);
+	}
+	/** On-demand GPU pick shares the visual shader including alpha and terrain mask. */
+	pick(pixel, tolerance = 0) {
+		if (!this.frame || this.status.status !== "supported") return null;
+		const gl = this.gl, w = gl.drawingBufferWidth, h = gl.drawingBufferHeight;
+		const previous = gl.getParameter(gl.FRAMEBUFFER_BINDING);
+		if (this.pickSize !== `${w}/${h}`) {
+			if (this.pickTexture) gl.deleteTexture(this.pickTexture);
+			if (this.pickFramebuffer) gl.deleteFramebuffer(this.pickFramebuffer);
+			this.pickTexture = gl.createTexture();
+			gl.activeTexture(gl.TEXTURE0);
+			gl.bindTexture(gl.TEXTURE_2D, this.pickTexture);
+			gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, w, h, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+			gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+			gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+			this.pickFramebuffer = gl.createFramebuffer();
+			gl.bindFramebuffer(gl.FRAMEBUFFER, this.pickFramebuffer);
+			gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.pickTexture, 0);
+			this.pickSize = `${w}/${h}`;
+		}
+		const dpr = w / this.map.getContainer().clientWidth;
+		const radius = Math.ceil(tolerance * dpr), x = Math.max(0, Math.floor(pixel[0] * dpr) - radius), y = Math.max(0, h - 1 - Math.floor(pixel[1] * dpr) - radius), rw = Math.min(w - x, 2 * radius + 1), rh = Math.min(h - y, 2 * radius + 1);
+		if (rw <= 0 || rh <= 0) {
+			gl.bindFramebuffer(gl.FRAMEBUFFER, previous);
+			return null;
+		}
+		gl.bindFramebuffer(gl.FRAMEBUFFER, this.pickFramebuffer);
+		gl.viewport(0, 0, w, h);
+		gl.enable(gl.SCISSOR_TEST);
+		gl.scissor(x, y, rw, rh);
+		gl.colorMask(true, true, true, true);
+		gl.clearColor(0, 0, 0, 0);
+		gl.clear(gl.COLOR_BUFFER_BIT);
+		this.draw(gl, true);
+		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);
+		gl.disable(gl.SCISSOR_TEST);
+		gl.bindFramebuffer(gl.FRAMEBUFFER, previous);
+		this.map.painter.context.setDirty();
+		this.map.painter.setBaseState();
+		this.map.triggerRepaint();
+		return id ? this.pins[id - 1]?.id ?? null : null;
+	}
+	/**
+	* Shared Mercator/globe clip-space projection converted to container pixels. Callers
+	* differ in elevation source and in whether/where a screen-mode lift offset applies
+	* — those stay at the call site, as they aren't part of the shared matrix math.
+	*/
+	projectToPixel(worldX, worldY, z) {
+		const { clip: c, horizon } = this.projection.project(worldX, worldY, z);
+		if (horizon < 0 || c[3] <= 0) return [NaN, NaN];
+		const width = this.map.getContainer().clientWidth, height = this.map.getContainer().clientHeight;
+		return [(c[0] / c[3] + 1) * width / 2, (1 - c[1] / c[3]) * height / 2];
+	}
+	footprint(id) {
+		const i = this.pins.findIndex((p) => p.id === id);
+		const pin = this.pins[i];
+		if (!pin || !this.ready || !this.frame || !Number.isFinite(this.elevations[i])) return null;
+		const p = pin.presentation, coord = pinMercator(pin.position);
+		coord.x += Math.round(this.origin[0] - coord.x);
+		const world = 512 * 2 ** this.map.getZoom();
+		const project = (z) => this.projectToPixel((coord.x - this.origin[0]) * world, (coord.y - this.origin[1]) * world, z);
+		const ground = project(this.elevations[i] ?? 0), attachment = p.mode === "world" ? project((this.elevations[i] ?? 0) + p.heightMeters) : [ground[0], ground[1] - p.liftPixels];
+		if (!attachment.every(Number.isFinite)) return null;
+		const scale = p.sizePixels / pin.octagonSize, padding = p.plate.enabled ? p.plate.padding : 0, halo = p.symbolHalo.opacity > 0 ? p.symbolHalo.width : 0, overhang = Math.max(0, halo - padding);
+		return {
+			ground,
+			attachment,
+			min: [attachment[0] - pin.resource.anchor[0] * scale - padding - overhang, attachment[1] - pin.resource.height * scale - padding * 2 - overhang],
+			max: [attachment[0] + (pin.resource.width - pin.resource.anchor[0]) * scale + padding + overhang, attachment[1] + overhang]
+		};
+	}
+	moveFromPixel(id, attachment) {
+		const pin = this.pins.find((pin) => pin.id === id);
+		if (!pin || !this.frame) return null;
+		const p = pin.presentation;
+		const project = (ll) => {
+			const c = pinMercator(ll);
+			c.x += Math.round(this.origin[0] - c.x);
+			const world = 512 * 2 ** this.map.getZoom();
+			const [px, py] = this.projectToPixel((c.x - this.origin[0]) * world, (c.y - this.origin[1]) * world, this.elevation(ll) + (p.mode === "world" ? p.heightMeters : 0));
+			return [px, py - (p.mode === "screen" ? p.liftPixels : 0)];
+		};
+		return invertPinProjection(project, pin.position, attachment, this.map.getProjection()?.type === "globe" ? 90 : void 0);
+	}
+	onRemove(_map, context) {
+		this.removed = true;
+		this.version++;
+		const gl = context;
+		this.onRemoveListeners();
+		if (this.pickTexture) gl.deleteTexture(this.pickTexture);
+		if (this.pickFramebuffer) gl.deleteFramebuffer(this.pickFramebuffer);
+		if (this.vao) gl.deleteVertexArray(this.vao);
+		if (this.buffer) gl.deleteBuffer(this.buffer);
+		if (this.program) gl.deleteProgram(this.program);
+	}
+};
+//#endregion
 //#region src/mercator.ts
 /**
 * Web Mercator world circumference in meters (2π × 6378137). The single source
@@ -255,6 +1285,25 @@ function emptyFC() {
 	};
 }
 /**
+* Builds the pin-status emitter passed to each `PinLayer`. Bound only to the
+* `listeners` set (never to the adapter itself, via `this`), so a `PinLayer`
+* holding onto this callback for its lifetime does not transitively retain
+* the whole `MapLibreAdapter` object graph (map, all layer handles, etc.).
+*/
+function createPinStatusDispatcher(listeners) {
+	return (event) => {
+		queueMicrotask(() => {
+			const errors = [];
+			for (const listener of listeners) try {
+				listener(event);
+			} catch (error) {
+				errors.push(error);
+			}
+			if (errors.length) throw new AggregateError(errors, "Pin presentation status listener errors");
+		});
+	};
+}
+/**
 * Build the paint expression for a circle layer with per-feature
 * `properties.style` overlay (ADR-0006). Each property prefers a value
 * pulled from `properties.style.<field>`, falling back to the layer default.
@@ -825,12 +1874,36 @@ var MapLibreAdapter = class extends BaseMapAdapter {
 	}
 	destroyLayer(handle) {
 		this.clearGroupBundles(handle);
+		handle.pinResources?.dispose();
 		for (const mlId of handle.mlLayerIds) if (this.map.getLayer(mlId)) this.map.removeLayer(mlId);
 		if (this.map.getSource(handle.sourceId)) this.map.removeSource(handle.sourceId);
 	}
-	applyFeatureGroups(layerId, groups) {
+	applyFeatureGroups(layerId, input) {
+		const groups = [];
+		for (const group of input) if (group.pin && this.getPinPresentationCapability().status !== "unsupported") {
+			const previous = groups[groups.length - 1];
+			if (previous?.pinBatch) previous.pinBatch.push(group.pin);
+			else groups.push({
+				id: `pin-run:${group.id}`,
+				features: [],
+				iconResources: [],
+				pinBatch: [group.pin]
+			});
+		} else groups.push({
+			...group,
+			id: `ordinary:${group.id}`
+		});
 		const handle = this.layers.get(layerId);
 		if (!handle) return;
+		const allPins = groups.flatMap((group) => group.pinBatch ?? []);
+		if (allPins.length) {
+			handle.pinResources ??= new PinResources(this.map);
+			const previousBatch = handle.lastPinBatch;
+			if (!(previousBatch !== void 0 && previousBatch.length === allPins.length && allPins.every((pin, index) => pin === previousBatch[index]))) {
+				handle.pinResources.setRoster(allPins);
+				handle.lastPinBatch = allPins;
+			}
+		}
 		const desiredGroupIds = new Set(groups.map((group) => group.id));
 		const previousGroupOrder = handle.groupOrder.filter((groupId) => desiredGroupIds.has(groupId));
 		const bundlesNeedingOrder = /* @__PURE__ */ new Set();
@@ -846,6 +1919,26 @@ var MapLibreAdapter = class extends BaseMapAdapter {
 				bundle = this.createGroupBundle(layerId, handle);
 				handle.groupBundles.set(group.id, bundle);
 			}
+			if (group.pinBatch) {
+				if (!bundle.pinLayer) {
+					const custom = new PinLayer(`${bundle.sourceId}-pins`, handle.pinResources, this.emitPinStatus);
+					this.map.addLayer(custom, handle.mlLayerIds[0]);
+					bundle.pinLayer = custom;
+					bundlesNeedingOrder.add(group.id);
+				}
+				const previous = bundle.pinSignature;
+				let changedIndices;
+				if (previous?.length === group.pinBatch.length) {
+					changedIndices = [];
+					for (let i = 0; i < group.pinBatch.length; i++) if (group.pinBatch[i] !== previous[i]) changedIndices.push(i);
+				}
+				if (!previous || bundle.pinResourceRevision !== handle.pinResources?.revision || previous.length !== group.pinBatch.length || !!changedIndices?.length) {
+					bundle.pinSignature = group.pinBatch;
+					bundle.pinResourceRevision = handle.pinResources?.revision;
+					bundle.pinLayer.setPins(group.pinBatch, changedIndices);
+				}
+				continue;
+			}
 			let contentChanged;
 			if (!isNewBundle && bundle.revision !== void 0 && group.revision !== void 0) {
 				contentChanged = bundle.revision !== group.revision;
@@ -864,6 +1957,11 @@ var MapLibreAdapter = class extends BaseMapAdapter {
 			if (this.reconcileGroupPaintSurfaces(handle, bundle, group.features)) bundlesNeedingOrder.add(group.id);
 			if (contentChanged || resourcesChanged) this.updateGroupBundleSource(bundle);
 		}
+		if (!allPins.length) {
+			handle.pinResources?.dispose();
+			handle.pinResources = void 0;
+			handle.lastPinBatch = void 0;
+		}
 		handle.groupOrder = groups.map((group) => group.id);
 		this.orderGroupBundles(handle, previousGroupOrder, handle.groupOrder, bundlesNeedingOrder);
 	}
@@ -888,6 +1986,7 @@ var MapLibreAdapter = class extends BaseMapAdapter {
 		};
 	}
 	destroyGroupBundle(bundle) {
+		if (bundle.pinLayer && this.map.getLayer(bundle.pinLayer.id)) this.map.removeLayer(bundle.pinLayer.id);
 		for (const overlay of bundle.overlays.values()) {
 			if (this.map.getLayer(overlay.layerId)) this.map.removeLayer(overlay.layerId);
 			if (this.map.getSource(overlay.sourceId)) this.map.removeSource(overlay.sourceId);
@@ -954,6 +2053,9 @@ var MapLibreAdapter = class extends BaseMapAdapter {
 		for (const bundle of handle.groupBundles.values()) this.destroyGroupBundle(bundle);
 		handle.groupBundles.clear();
 		handle.groupOrder = [];
+		handle.pinResources?.dispose();
+		handle.pinResources = void 0;
+		handle.lastPinBatch = void 0;
 	}
 	requiredIconIds(group) {
 		const referenced = new Set(group.features.flatMap((feature) => {
@@ -1099,13 +2201,14 @@ var MapLibreAdapter = class extends BaseMapAdapter {
 			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);
 				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);
 				}
 			}
-			beforeId = firstBundleLayerId(bundle) ?? beforeId;
+			beforeId = bundle.pinLayer?.id ?? firstBundleLayerId(bundle) ?? beforeId;
 		}
 	}
 	nativeLayerIds(handle) {
@@ -1200,10 +2303,11 @@ var MapLibreAdapter = class extends BaseMapAdapter {
 		for (const event of this.viewChangeEvents()) this.map.off(event, token.fn);
 	}
 	viewChangeEvents() {
-		return this.viewChangeMode === "settle" ? ["moveend"] : [
+		return this.viewChangeMode === "settle" ? ["moveend", "projectiontransition"] : [
 			"move",
 			"resize",
-			"moveend"
+			"moveend",
+			"projectiontransition"
 		];
 	}
 	createEditPointerDriver() {
@@ -1464,7 +2568,7 @@ var MapLibreAdapter = class extends BaseMapAdapter {
 				id: feature.id,
 				geometry: feature.geometry,
 				properties: feature.properties
-			})), this.featureCache.get(layerId) ?? []);
+			})), (this.featureCache.get(layerId) ?? []).filter((f) => !f.properties?.pinPresentation));
 			const size = this.getViewportSize();
 			const candidate = evaluatePickCandidates(relevantFeatures.map(({ feature, nativeHit, visualOrder }) => {
 				const iconId = feature.properties?.iconId;
@@ -1495,6 +2599,17 @@ var MapLibreAdapter = class extends BaseMapAdapter {
 				},
 				bearing: this.getBearing()
 			});
+			const pinHit = this.pinHit(layerId, [x, y], tol);
+			if (pinHit && (!candidate || pinHit.order >= (this.getFeatureGroupOrder(layerId, candidate.feature.id) ?? -1))) {
+				handler({
+					id: pinHit.id,
+					feature: pinHit.feature,
+					pixel: [x, y],
+					coordinate: [e.lngLat.lng, e.lngLat.lat],
+					originalEvent
+				});
+				return;
+			}
 			if (!candidate) return;
 			const cmId = candidate.graphicId;
 			if (cmId == null) return;
@@ -1511,6 +2626,74 @@ var MapLibreAdapter = class extends BaseMapAdapter {
 			return () => this.map.off("click", onMlClick);
 		});
 	}
+	pinStatusListeners = /* @__PURE__ */ new Set();
+	emitPinStatus = createPinStatusDispatcher(this.pinStatusListeners);
+	onPinPresentationStatusChange(handler) {
+		this.pinStatusListeners.add(handler);
+		return () => this.pinStatusListeners.delete(handler);
+	}
+	/**
+	* Pin layers across this adapter's group bundles.
+	* - With no `handle`: every layer's bundles, in bundle-map (creation)
+	*   order — fine for id-based lookups where only "does one match" matters.
+	* - With `handle`: only that layer's bundles, walked topmost-first (reverse
+	*   paint order) — required for hit-testing, where the first hit must be
+	*   the visually topmost pin.
+	*/
+	*pinLayers(handle) {
+		if (handle) {
+			for (const groupId of [...handle.groupOrder].reverse()) {
+				const pinLayer = handle.groupBundles.get(groupId)?.pinLayer;
+				if (pinLayer) yield pinLayer;
+			}
+			return;
+		}
+		for (const h of this.layers.values()) for (const bundle of h.groupBundles.values()) if (bundle.pinLayer) yield bundle.pinLayer;
+	}
+	/** First non-null/undefined result of `fn` across all pin layers, else null. */
+	findPinLayer(fn) {
+		for (const pinLayer of this.pinLayers()) {
+			const result = fn(pinLayer);
+			if (result != null) return result;
+		}
+		return null;
+	}
+	getPinPresentationCapability(graphicId) {
+		if (!(maplibregl.getVersion?.() ?? "").startsWith("6.")) return {
+			status: "unsupported",
+			reason: "Pins require MapLibre 6"
+		};
+		if (graphicId) {
+			const status = this.findPinLayer((pinLayer) => pinLayer.has(graphicId) ? pinLayer.getStatus(graphicId) : null);
+			if (status) return status;
+		}
+		return { status: "supported" };
+	}
+	getPinFootprint(id) {
+		return this.findPinLayer((pinLayer) => pinLayer.footprint(id));
+	}
+	movePinFromPixel(id, attachment) {
+		return this.findPinLayer((pinLayer) => pinLayer.moveFromPixel(id, attachment));
+	}
+	pinHit(layerId, pixel, tolerance) {
+		const handle = this.layers.get(layerId);
+		if (!handle) return null;
+		for (const pinLayer of this.pinLayers(handle)) {
+			const id = pinLayer.pick(pixel, tolerance);
+			if (!id) continue;
+			const feature = this.featureCache.get(layerId)?.find((f) => f.properties?.graphicId === id);
+			if (feature) return {
+				id,
+				feature,
+				order: this.getFeatureGroupOrder(layerId, feature.id) ?? 0
+			};
+		}
+		return null;
+	}
+	pickPin(id, pixel, tolerance) {
+		for (const [layerId] of this.layers) if (this.pinHit(layerId, pixel, tolerance)?.id === id) return true;
+		return false;
+	}
 	setGlobeMode(enabled) {
 		if (enabled) this.map.setProjection({ type: "globe" });
 		else this.map.setProjection({ type: "mercator" });