maplibre-gl-layers 0.10.0 → 0.11.0

package/dist/index.mjs

@@ -3,12 +3,12 @@ var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { en
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 /*!
  * name: maplibre-gl-layers
- * version: 0.10.0
+ * version: 0.11.0
  * description: MapLibre's layer extension library enabling the display, movement, and modification of large numbers of dynamic sprite images
  * author: Kouji Matsui (@kekyo@mi.kekyo.net)
  * license: MIT
  * repository.url: https://github.com/kekyo/maplibre-gl-layers.git
- * git.commit.hash: 58b99588e56fc80c6874d78a17e91a50901abc17
+ * git.commit.hash: 371efb126f281333d59ec75cfe788d45f3b1482e
  */
 const UNLIMITED_SPRITE_SCALING_OPTIONS = {
   metersPerPixel: 1,
@@ -21934,13 +21934,6 @@ const applySurfaceDisplacement = (baseLng, baseLat, east, north) => {
     lat: baseLat + deltaLat
   };
 };
-const screenToClip = (x, y, drawingBufferWidth, drawingBufferHeight, pixelRatio) => {
-  const deviceX = x * pixelRatio;
-  const deviceY = y * pixelRatio;
-  const clipX = deviceX / drawingBufferWidth * 2 - 1;
-  const clipY = 1 - deviceY / drawingBufferHeight * 2;
-  return [clipX, clipY];
-};
 const clipToScreen = (clipPosition, drawingBufferWidth, drawingBufferHeight, pixelRatio) => {
   const [clipX, clipY, , clipW] = clipPosition;
   if (!Number.isFinite(clipW) || clipW === 0) {
@@ -22085,41 +22078,55 @@ const calculateBillboardCenterPosition = (params) => {
     offsetShift
   };
 };
-const BILLBOARD_BASE_CORNERS = [
-  [-1, 1],
-  [1, 1],
-  [-1, -1],
-  [1, -1]
-];
-const calculateBillboardCornerScreenPositions = (params) => {
+const computeSurfaceCornerShaderModel = (params) => {
   var _a, _b;
-  const { centerX, centerY, halfWidth, halfHeight, anchor, totalRotateDeg } = params;
+  const {
+    baseLngLat,
+    worldWidthMeters,
+    worldHeightMeters,
+    anchor,
+    totalRotateDeg,
+    offsetMeters
+  } = params;
+  const halfWidth = worldWidthMeters / 2;
+  const halfHeight = worldHeightMeters / 2;
   if (halfWidth <= 0 || halfHeight <= 0) {
-    return UV_CORNERS.map(([u, v]) => ({ x: centerX, y: centerY, u, v }));
+    const cosLat2 = Math.cos(baseLngLat.lat * DEG2RAD);
+    const cosLatClamped2 = Math.max(cosLat2, MIN_COS_LAT);
+    const deltaLat = offsetMeters.north / EARTH_RADIUS_METERS * RAD2DEG;
+    const deltaLng = offsetMeters.east / (EARTH_RADIUS_METERS * cosLatClamped2) * RAD2DEG;
+    return SURFACE_BASE_CORNERS$1.map(() => ({
+      east: offsetMeters.east,
+      north: offsetMeters.north,
+      lng: baseLngLat.lng + deltaLng,
+      lat: baseLngLat.lat + deltaLat
+    }));
   }
-  const anchorOffsetX = ((_a = anchor == null ? void 0 : anchor.x) != null ? _a : 0) * halfWidth;
-  const anchorOffsetY = ((_b = anchor == null ? void 0 : anchor.y) != null ? _b : 0) * halfHeight;
+  const anchorEast = ((_a = anchor == null ? void 0 : anchor.x) != null ? _a : 0) * halfWidth;
+  const anchorNorth = ((_b = anchor == null ? void 0 : anchor.y) != null ? _b : 0) * halfHeight;
   const rad = -totalRotateDeg * DEG2RAD;
-  const cosR = Math.cos(rad);
   const sinR = Math.sin(rad);
-  const corners = [];
-  for (let i = 0; i < BILLBOARD_BASE_CORNERS.length; i++) {
-    const [cornerXNorm, cornerYNorm] = BILLBOARD_BASE_CORNERS[i];
-    const [u, v] = UV_CORNERS[i];
-    const cornerX = cornerXNorm * halfWidth;
-    const cornerY = cornerYNorm * halfHeight;
-    const shiftedX = cornerX - anchorOffsetX;
-    const shiftedY = cornerY - anchorOffsetY;
-    const rotatedX = shiftedX * cosR - shiftedY * sinR;
-    const rotatedY = shiftedX * sinR + shiftedY * cosR;
-    corners.push({
-      x: centerX + rotatedX,
-      y: centerY - rotatedY,
-      u,
-      v
-    });
-  }
-  return corners;
+  const cosR = Math.cos(rad);
+  const cosLat = Math.cos(baseLngLat.lat * DEG2RAD);
+  const cosLatClamped = Math.max(cosLat, MIN_COS_LAT);
+  return SURFACE_BASE_CORNERS$1.map(([eastNorm, northNorm]) => {
+    const cornerEast = eastNorm * halfWidth;
+    const cornerNorth = northNorm * halfHeight;
+    const localEast = cornerEast - anchorEast;
+    const localNorth = cornerNorth - anchorNorth;
+    const rotatedEast = localEast * cosR - localNorth * sinR;
+    const rotatedNorth = localEast * sinR + localNorth * cosR;
+    const east = rotatedEast + offsetMeters.east;
+    const north = rotatedNorth + offsetMeters.north;
+    const deltaLat = north / EARTH_RADIUS_METERS * RAD2DEG;
+    const deltaLng = east / (EARTH_RADIUS_METERS * cosLatClamped) * RAD2DEG;
+    return {
+      east,
+      north,
+      lng: baseLngLat.lng + deltaLng,
+      lat: baseLngLat.lat + deltaLat
+    };
+  });
 };
 const calculateSurfaceCenterPosition = (params) => {
   var _a, _b;
@@ -22229,7 +22236,7 @@ const calculateSurfaceCenterPosition = (params) => {
     anchorlessLngLat
   };
 };
-const SURFACE_BASE_CORNERS = [
+const SURFACE_BASE_CORNERS$1 = [
   [-1, 1],
   [1, 1],
   [-1, -1],
@@ -22245,7 +22252,7 @@ const calculateSurfaceCornerDisplacements = (params) => {
     offsetMeters
   } = params;
   if (worldWidthMeters <= 0 || worldHeightMeters <= 0) {
-    return SURFACE_BASE_CORNERS.map(() => ({
+    return SURFACE_BASE_CORNERS$1.map(() => ({
       east: offsetMeters.east,
       north: offsetMeters.north
     }));
@@ -22258,7 +22265,7 @@ const calculateSurfaceCornerDisplacements = (params) => {
   const cosR = Math.cos(rad);
   const sinR = Math.sin(rad);
   const corners = [];
-  for (const [eastNorm, northNorm] of SURFACE_BASE_CORNERS) {
+  for (const [eastNorm, northNorm] of SURFACE_BASE_CORNERS$1) {
     const cornerEast = eastNorm * halfWidth;
     const cornerNorth = northNorm * halfHeight;
     const localEast = cornerEast - anchorEast;
@@ -22509,12 +22516,262 @@ const applyOffsetUpdate = (image, nextOffset, options = {}) => {
   applyOffsetDegUpdate(image, nextOffset, options.deg);
   applyOffsetMetersUpdate(image, nextOffset, options.meters);
 };
+const DEFAULT_MAX_ITEMS_PER_NODE = 16;
+const DEFAULT_MAX_DEPTH = 8;
+const DEFAULT_LOOSENESS = 1.5;
+const createNode = (bounds, looseness, depth) => ({
+  bounds,
+  looseBounds: expandRect(bounds, looseness),
+  items: [],
+  children: null,
+  depth
+});
+const normalizeRect = (rect) => {
+  const x0 = Math.min(rect.x0, rect.x1);
+  const y0 = Math.min(rect.y0, rect.y1);
+  const x1 = Math.max(rect.x0, rect.x1);
+  const y1 = Math.max(rect.y0, rect.y1);
+  return { x0, y0, x1, y1 };
+};
+const isFiniteRect = (rect) => Number.isFinite(rect.x0) && Number.isFinite(rect.y0) && Number.isFinite(rect.x1) && Number.isFinite(rect.y1);
+const expandRect = (rect, looseness) => {
+  if (looseness === 1) {
+    return rect;
+  }
+  const width = rect.x1 - rect.x0;
+  const height = rect.y1 - rect.y0;
+  const halfWidth = width * looseness / 2;
+  const halfHeight = height * looseness / 2;
+  const centerX = rect.x0 + width / 2;
+  const centerY = rect.y0 + height / 2;
+  return {
+    x0: centerX - halfWidth,
+    y0: centerY - halfHeight,
+    x1: centerX + halfWidth,
+    y1: centerY + halfHeight
+  };
+};
+const rectContainsRectInclusive = (container, target) => container.x0 <= target.x0 && container.y0 <= target.y0 && container.x1 >= target.x1 && container.y1 >= target.y1;
+const rectsOverlapInclusive = (a, b) => !(a.x1 < b.x0 || a.x0 > b.x1 || a.y1 < b.y0 || a.y0 > b.y1);
+const rectEquals = (a, b) => a.x0 === b.x0 && a.y0 === b.y0 && a.x1 === b.x1 && a.y1 === b.y1;
+const createLooseQuadTree = (options) => {
+  var _a, _b, _c;
+  const maxItemsPerNode = (_a = options.maxItemsPerNode) != null ? _a : DEFAULT_MAX_ITEMS_PER_NODE;
+  const maxDepth = (_b = options.maxDepth) != null ? _b : DEFAULT_MAX_DEPTH;
+  const looseness = (_c = options.looseness) != null ? _c : DEFAULT_LOOSENESS;
+  if (maxItemsPerNode <= 0) {
+    throw new Error("maxItemsPerNode must be greater than 0.");
+  }
+  if (maxDepth < 0) {
+    throw new Error("maxDepth must be 0 or greater.");
+  }
+  if (!(looseness >= 1)) {
+    throw new Error("looseness must be greater than or equal to 1.");
+  }
+  const normalizedBounds = normalizeRect(options.bounds);
+  if (!isFiniteRect(normalizedBounds)) {
+    throw new Error("Bounds must have finite coordinates.");
+  }
+  let root = createNode(normalizedBounds, looseness, 0);
+  let count = 0;
+  let registry = /* @__PURE__ */ new WeakMap();
+  const insertIntoNode = (node, quadItem) => {
+    if (node.children) {
+      const childIndex = findChildIndex(node.children, quadItem.rect);
+      if (childIndex !== -1) {
+        insertIntoNode(node.children[childIndex], quadItem);
+        return;
+      }
+    }
+    quadItem.node = node;
+    quadItem.index = node.items.length;
+    node.items.push(quadItem);
+    if (node.items.length > maxItemsPerNode && node.depth < maxDepth) {
+      if (!node.children) {
+        subdivide(node);
+      }
+      const children = node.children;
+      if (!children) {
+        return;
+      }
+      let i = 0;
+      while (i < node.items.length) {
+        const candidate = node.items[i];
+        const childIndex = findChildIndex(children, candidate.rect);
+        if (childIndex !== -1) {
+          detachFromNode(candidate);
+          insertIntoNode(children[childIndex], candidate);
+        } else {
+          i += 1;
+        }
+      }
+    }
+  };
+  const removeQuadItem = (quadItem) => {
+    detachFromNode(quadItem);
+    registry.delete(quadItem.item);
+  };
+  const detachFromNode = (quadItem) => {
+    const node = quadItem.node;
+    const index = quadItem.index;
+    if (index < 0 || index >= node.items.length) {
+      return;
+    }
+    const lastIndex = node.items.length - 1;
+    if (index !== lastIndex) {
+      const moved = node.items[lastIndex];
+      node.items[index] = moved;
+      moved.index = index;
+    }
+    node.items.pop();
+    quadItem.index = -1;
+    quadItem.node = node;
+  };
+  const reassignIfPossible = (quadItem) => {
+    const node = quadItem.node;
+    if (!node.children) {
+      return;
+    }
+    const childIndex = findChildIndex(node.children, quadItem.rect);
+    if (childIndex === -1) {
+      return;
+    }
+    detachFromNode(quadItem);
+    insertIntoNode(node.children[childIndex], quadItem);
+  };
+  const add = (item) => {
+    const rect = normalizeRect(item);
+    if (!rectContainsRectInclusive(root.bounds, rect)) {
+      throw new Error("Item rectangle is outside of quadtree bounds.");
+    }
+    const quadItem = {
+      item,
+      rect,
+      node: root,
+      index: -1
+    };
+    insertIntoNode(root, quadItem);
+    registry.set(item, quadItem);
+    count += 1;
+  };
+  const remove = (x0, y0, x1, y1, item) => {
+    const quadItem = registry.get(item);
+    if (!quadItem) {
+      return false;
+    }
+    const rect = normalizeRect({ x0, y0, x1, y1 });
+    if (!rectEquals(rect, quadItem.rect)) {
+      return false;
+    }
+    removeQuadItem(quadItem);
+    count -= 1;
+    return true;
+  };
+  const update = (oldX0, oldY0, oldX1, oldY1, newX0, newY0, newX1, newY1, item) => {
+    const quadItem = registry.get(item);
+    if (!quadItem) {
+      return false;
+    }
+    const currentRect = quadItem.rect;
+    const expectedOldRect = normalizeRect({
+      x0: oldX0,
+      y0: oldY0,
+      x1: oldX1,
+      y1: oldY1
+    });
+    if (!rectEquals(currentRect, expectedOldRect)) {
+      return false;
+    }
+    const newRect = normalizeRect({
+      x0: newX0,
+      y0: newY0,
+      x1: newX1,
+      y1: newY1
+    });
+    if (!rectContainsRectInclusive(root.bounds, newRect)) {
+      throw new Error("Updated rectangle is outside of quadtree bounds.");
+    }
+    if (rectContainsRectInclusive(quadItem.node.looseBounds, newRect)) {
+      quadItem.rect = newRect;
+      reassignIfPossible(quadItem);
+      return true;
+    }
+    detachFromNode(quadItem);
+    quadItem.rect = newRect;
+    insertIntoNode(root, quadItem);
+    return true;
+  };
+  const lookup = (x0, y0, x1, y1) => {
+    const rect = normalizeRect({ x0, y0, x1, y1 });
+    const results = [];
+    collectFromNode(root, rect, results);
+    return results;
+  };
+  const clear = () => {
+    root = createNode(normalizedBounds, looseness, 0);
+    registry = /* @__PURE__ */ new WeakMap();
+    count = 0;
+  };
+  const collectFromNode = (node, rect, results) => {
+    if (!rectsOverlapInclusive(node.looseBounds, rect)) {
+      return;
+    }
+    for (const quadItem of node.items) {
+      if (rectsOverlapInclusive(quadItem.rect, rect)) {
+        results.push(quadItem.item);
+      }
+    }
+    if (!node.children) {
+      return;
+    }
+    for (const child of node.children) {
+      collectFromNode(child, rect, results);
+    }
+  };
+  const findChildIndex = (children, rect) => {
+    for (let i = 0; i < children.length; i += 1) {
+      const child = children[i];
+      if (rectContainsRectInclusive(child.looseBounds, rect)) {
+        return i;
+      }
+    }
+    return -1;
+  };
+  const subdivide = (node) => {
+    if (node.children) {
+      return;
+    }
+    const { bounds } = node;
+    const splitX = bounds.x0 + (bounds.x1 - bounds.x0) / 2;
+    const splitY = bounds.y0 + (bounds.y1 - bounds.y0) / 2;
+    const childrenBounds = [
+      normalizeRect({ x0: bounds.x0, y0: bounds.y0, x1: splitX, y1: splitY }),
+      normalizeRect({ x0: splitX, y0: bounds.y0, x1: bounds.x1, y1: splitY }),
+      normalizeRect({ x0: bounds.x0, y0: splitY, x1: splitX, y1: bounds.y1 }),
+      normalizeRect({ x0: splitX, y0: splitY, x1: bounds.x1, y1: bounds.y1 })
+    ];
+    node.children = childrenBounds.map(
+      (childBounds) => createNode(childBounds, looseness, node.depth + 1)
+    );
+  };
+  return {
+    get size() {
+      return count;
+    },
+    add,
+    remove,
+    update,
+    lookup,
+    clear
+  };
+};
 const DEFAULT_ANCHOR = { x: 0, y: 0 };
 const DEFAULT_AUTO_ROTATION_MIN_DISTANCE_METERS = 20;
 const DEFAULT_IMAGE_OFFSET = {
   offsetMeters: 0,
   offsetDeg: 0
 };
+const HIT_TEST_QUERY_RADIUS_PIXELS = 32;
 const MIN_CLIP_W = 1e-6;
 const MIN_CLIP_Z_EPSILON = 1e-7;
 const EPS_NDC = 1e-6;
@@ -22605,7 +22862,7 @@ const resolveGlMagFilter = (glContext, filter) => {
       return glContext.LINEAR;
   }
 };
-const calculatePerspectiveRatio = (mapInstance, location2) => {
+const calculatePerspectiveRatio = (mapInstance, location2, cachedMercator) => {
   var _a, _b, _c;
   const transform = mapInstance.transform;
   if (!transform) {
@@ -22617,7 +22874,7 @@ const calculatePerspectiveRatio = (mapInstance, location2) => {
     return 1;
   }
   try {
-    const mercator = maplibreGlExports.MercatorCoordinate.fromLngLat(
+    const mercator = cachedMercator != null ? cachedMercator : maplibreGlExports.MercatorCoordinate.fromLngLat(
       { lng: location2.lng, lat: location2.lat },
       (_b = location2.z) != null ? _b : 0
     );
@@ -22750,10 +23007,59 @@ const QUAD_VERTEX_COUNT = 6;
 const VERTEX_SHADER_SOURCE = `
 attribute vec4 a_position;
 attribute vec2 a_uv;
+uniform vec2 u_screenToClipScale;
+uniform vec2 u_screenToClipOffset;
+uniform float u_billboardMode;
+uniform float u_surfaceMode;
+uniform vec2 u_billboardCenter;
+uniform vec2 u_billboardHalfSize;
+uniform vec2 u_billboardAnchor;
+uniform vec2 u_billboardSinCos;
+uniform float u_surfaceClipEnabled;
+uniform vec4 u_surfaceClipCenter;
+uniform vec4 u_surfaceClipBasisEast;
+uniform vec4 u_surfaceClipBasisNorth;
+uniform float u_surfaceDepthBias;
 varying vec2 v_uv;
+vec2 computeBillboardCorner(vec2 uv) {
+  vec2 base = vec2(uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0);
+  vec2 anchorShift = vec2(u_billboardAnchor.x * u_billboardHalfSize.x, u_billboardAnchor.y * u_billboardHalfSize.y);
+  vec2 shifted = vec2(base.x * u_billboardHalfSize.x, base.y * u_billboardHalfSize.y) - anchorShift;
+  float sinR = u_billboardSinCos.x;
+  float cosR = u_billboardSinCos.y;
+  vec2 rotated = vec2(
+    shifted.x * cosR - shifted.y * sinR,
+    shifted.x * sinR + shifted.y * cosR
+  );
+  return vec2(
+    u_billboardCenter.x + rotated.x,
+    u_billboardCenter.y - rotated.y
+  );
+}
+vec4 computeSurfaceCorner(vec2 corner) {
+  if (u_surfaceClipEnabled < 0.5) {
+    return vec4(0.0, 0.0, 0.0, 1.0);
+  }
+  vec4 clip = u_surfaceClipCenter
+    + (corner.x * u_surfaceClipBasisEast)
+    + (corner.y * u_surfaceClipBasisNorth);
+  clip.z += u_surfaceDepthBias * clip.w;
+  return clip;
+}
 void main() {
   v_uv = a_uv;
-  gl_Position = a_position;
+  vec4 position;
+  if (u_billboardMode > 0.5) {
+    vec2 screenPosition = computeBillboardCorner(a_uv);
+    position = vec4(screenPosition, 0.0, 1.0);
+  } else if (u_surfaceMode > 0.5) {
+    vec2 baseCorner = vec2(a_position.x, a_position.y);
+    position = computeSurfaceCorner(baseCorner);
+  } else {
+    position = a_position;
+  }
+  position.xy = position.xy * u_screenToClipScale + u_screenToClipOffset;
+  gl_Position = position;
 }
 `;
 const FRAGMENT_SHADER_SOURCE = `
@@ -22772,6 +23078,175 @@ const INITIAL_QUAD_VERTICES = new Float32Array(
 const QUAD_VERTEX_SCRATCH = new Float32Array(
   QUAD_VERTEX_COUNT * VERTEX_COMPONENT_COUNT
 );
+const DEBUG_OUTLINE_VERTEX_SHADER_SOURCE = `
+attribute vec4 a_position;
+uniform vec2 u_screenToClipScale;
+uniform vec2 u_screenToClipOffset;
+void main() {
+  vec4 position = a_position;
+  position.xy = position.xy * u_screenToClipScale + u_screenToClipOffset;
+  gl_Position = position;
+}
+`;
+const DEBUG_OUTLINE_FRAGMENT_SHADER_SOURCE = `
+precision mediump float;
+uniform vec4 u_color;
+void main() {
+  gl_FragColor = u_color;
+}
+`;
+const DEBUG_OUTLINE_VERTEX_COUNT = 4;
+const DEBUG_OUTLINE_POSITION_COMPONENT_COUNT = 4;
+const DEBUG_OUTLINE_VERTEX_STRIDE = DEBUG_OUTLINE_POSITION_COMPONENT_COUNT * FLOAT_SIZE;
+const DEBUG_OUTLINE_VERTEX_SCRATCH = new Float32Array(
+  DEBUG_OUTLINE_VERTEX_COUNT * DEBUG_OUTLINE_POSITION_COMPONENT_COUNT
+);
+const DEBUG_OUTLINE_COLOR = [
+  1,
+  0,
+  0,
+  1
+];
+const DEBUG_OUTLINE_CORNER_ORDER = [0, 1, 3, 2];
+const BILLBOARD_BASE_CORNERS = [
+  [-1, 1],
+  [1, 1],
+  [-1, -1],
+  [1, -1]
+];
+const SURFACE_BASE_CORNERS = [
+  [-1, 1],
+  [1, 1],
+  [-1, -1],
+  [1, -1]
+];
+const computeBillboardCornersShaderModel = ({
+  centerX,
+  centerY,
+  halfWidth,
+  halfHeight,
+  anchor,
+  rotationDeg
+}) => {
+  var _a, _b;
+  const anchorX = (_a = anchor == null ? void 0 : anchor.x) != null ? _a : 0;
+  const anchorY = (_b = anchor == null ? void 0 : anchor.y) != null ? _b : 0;
+  const rad = -rotationDeg * DEG2RAD;
+  const cosR = Math.cos(rad);
+  const sinR = Math.sin(rad);
+  return BILLBOARD_BASE_CORNERS.map(([cornerXNorm, cornerYNorm], index) => {
+    const cornerX = cornerXNorm * halfWidth;
+    const cornerY = cornerYNorm * halfHeight;
+    const shiftedX = cornerX - anchorX * halfWidth;
+    const shiftedY = cornerY - anchorY * halfHeight;
+    const rotatedX = shiftedX * cosR - shiftedY * sinR;
+    const rotatedY = shiftedX * sinR + shiftedY * cosR;
+    const [u, v] = UV_CORNERS[index];
+    return {
+      x: centerX + rotatedX,
+      y: centerY - rotatedY,
+      u,
+      v
+    };
+  });
+};
+const calculateWorldToMercatorScale = (base, altitudeMeters) => {
+  const origin = maplibreGlExports.MercatorCoordinate.fromLngLat(
+    { lng: base.lng, lat: base.lat },
+    altitudeMeters
+  );
+  const eastLngLat = applySurfaceDisplacement(base.lng, base.lat, 1, 0);
+  const eastCoord = maplibreGlExports.MercatorCoordinate.fromLngLat(
+    { lng: eastLngLat.lng, lat: eastLngLat.lat },
+    altitudeMeters
+  );
+  const northLngLat = applySurfaceDisplacement(base.lng, base.lat, 0, 1);
+  const northCoord = maplibreGlExports.MercatorCoordinate.fromLngLat(
+    { lng: northLngLat.lng, lat: northLngLat.lat },
+    altitudeMeters
+  );
+  return {
+    east: eastCoord.x - origin.x,
+    north: northCoord.y - origin.y
+  };
+};
+const prepareSurfaceShaderInputs = (params) => {
+  var _a, _b;
+  const {
+    baseLngLat,
+    worldWidthMeters,
+    worldHeightMeters,
+    anchor,
+    totalRotateDeg,
+    offsetMeters,
+    displacedCenter,
+    altitudeMeters,
+    depthBiasNdc,
+    scaleAdjustment,
+    centerDisplacement
+  } = params;
+  const halfSizeMeters = {
+    east: worldWidthMeters / 2,
+    north: worldHeightMeters / 2
+  };
+  const rotationRad = -totalRotateDeg * DEG2RAD;
+  const sinR = Math.sin(rotationRad);
+  const cosR = Math.cos(rotationRad);
+  const mercatorCenter = maplibreGlExports.MercatorCoordinate.fromLngLat(
+    { lng: displacedCenter.lng, lat: displacedCenter.lat },
+    altitudeMeters
+  );
+  const worldToMercatorScale = calculateWorldToMercatorScale(
+    displacedCenter,
+    altitudeMeters
+  );
+  const cornerModel = computeSurfaceCornerShaderModel({
+    baseLngLat,
+    worldWidthMeters,
+    worldHeightMeters,
+    anchor,
+    totalRotateDeg,
+    offsetMeters
+  });
+  return {
+    mercatorCenter: {
+      x: mercatorCenter.x,
+      y: mercatorCenter.y,
+      z: (_a = mercatorCenter.z) != null ? _a : 0
+    },
+    worldToMercatorScale,
+    halfSizeMeters,
+    anchor,
+    offsetMeters: {
+      east: offsetMeters.east,
+      north: offsetMeters.north
+    },
+    sinCos: { sin: sinR, cos: cosR },
+    totalRotateDeg,
+    depthBiasNdc,
+    centerDisplacement: {
+      east: centerDisplacement.east,
+      north: centerDisplacement.north
+    },
+    baseLngLat,
+    displacedCenter: {
+      lng: displacedCenter.lng,
+      lat: displacedCenter.lat,
+      z: (_b = displacedCenter.z) != null ? _b : altitudeMeters
+    },
+    scaleAdjustment,
+    corners: cornerModel.map((corner) => ({
+      east: corner.east,
+      north: corner.north,
+      lng: corner.lng,
+      lat: corner.lat
+    })),
+    clipCenter: { x: 0, y: 0, z: 0, w: 1 },
+    clipBasisEast: { x: 0, y: 0, z: 0, w: 0 },
+    clipBasisNorth: { x: 0, y: 0, z: 0, w: 0 },
+    clipCorners: []
+  };
+};
 const compileShader = (glContext, type, source) => {
   var _a;
   const shader = glContext.createShader(type);
@@ -23205,42 +23680,403 @@ const createImageStateFromInit = (imageInit, subLayer, order) => {
     lastCommandOffsetDeg: initialOffset.offsetDeg,
     lastCommandOffsetMeters: initialOffset.offsetMeters
   };
-  const rotateInitOption = (_i = (_h = imageInit.interpolation) == null ? void 0 : _h.rotateDeg) != null ? _i : null;
-  if (rotateInitOption) {
-    state.rotationInterpolationOptions = cloneInterpolationOptions(rotateInitOption);
-  }
-  syncImageRotationChannel(state);
-  return state;
-};
-const createSpriteLayer = (options) => {
-  var _a;
-  const id = (_a = options == null ? void 0 : options.id) != null ? _a : "sprite-layer";
-  const resolvedScaling = resolveScalingOptions(options == null ? void 0 : options.spriteScaling);
-  const resolvedTextureFiltering = resolveTextureFilteringOptions(
-    options == null ? void 0 : options.textureFiltering
-  );
-  let gl = null;
-  let map = null;
-  let program = null;
-  let vertexBuffer = null;
-  let attribPositionLocation = -1;
-  let attribUvLocation = -1;
-  let uniformTextureLocation = null;
-  let uniformOpacityLocation = null;
-  let anisotropyExtension = null;
-  let maxSupportedAnisotropy = 1;
-  const images = /* @__PURE__ */ new Map();
-  const queuedTextureIds = /* @__PURE__ */ new Set();
-  const queueTextureUpload = (image) => {
-    queuedTextureIds.add(image.id);
+  const rotateInitOption = (_i = (_h = imageInit.interpolation) == null ? void 0 : _h.rotateDeg) != null ? _i : null;
+  if (rotateInitOption) {
+    state.rotationInterpolationOptions = cloneInterpolationOptions(rotateInitOption);
+  }
+  syncImageRotationChannel(state);
+  return state;
+};
+const createSpriteLayer = (options) => {
+  var _a;
+  const id = (_a = options == null ? void 0 : options.id) != null ? _a : "sprite-layer";
+  const resolvedScaling = resolveScalingOptions(options == null ? void 0 : options.spriteScaling);
+  const resolvedTextureFiltering = resolveTextureFilteringOptions(
+    options == null ? void 0 : options.textureFiltering
+  );
+  const showDebugBounds = (options == null ? void 0 : options.showDebugBounds) === true;
+  let gl = null;
+  let map = null;
+  let program = null;
+  let vertexBuffer = null;
+  let attribPositionLocation = -1;
+  let attribUvLocation = -1;
+  let uniformTextureLocation = null;
+  let uniformOpacityLocation = null;
+  let uniformScreenToClipScaleLocation = null;
+  let uniformScreenToClipOffsetLocation = null;
+  let uniformBillboardModeLocation = null;
+  let uniformBillboardCenterLocation = null;
+  let uniformBillboardHalfSizeLocation = null;
+  let uniformBillboardAnchorLocation = null;
+  let uniformBillboardSinCosLocation = null;
+  let uniformSurfaceModeLocation = null;
+  let uniformSurfaceDepthBiasLocation = null;
+  let uniformSurfaceClipEnabledLocation = null;
+  let uniformSurfaceClipCenterLocation = null;
+  let uniformSurfaceClipBasisEastLocation = null;
+  let uniformSurfaceClipBasisNorthLocation = null;
+  let anisotropyExtension = null;
+  let maxSupportedAnisotropy = 1;
+  let debugProgram = null;
+  let debugVertexBuffer = null;
+  let debugAttribPositionLocation = -1;
+  let debugUniformColorLocation = null;
+  let debugUniformScreenToClipScaleLocation = null;
+  let debugUniformScreenToClipOffsetLocation = null;
+  const images = /* @__PURE__ */ new Map();
+  const queuedTextureIds = /* @__PURE__ */ new Set();
+  const queueTextureUpload = (image) => {
+    queuedTextureIds.add(image.id);
+  };
+  const cancelQueuedTextureUpload = (imageId) => {
+    queuedTextureIds.delete(imageId);
+  };
+  const clearTextureQueue = () => {
+    queuedTextureIds.clear();
+  };
+  const sprites = /* @__PURE__ */ new Map();
+  const resolveSpriteMercator = (sprite) => {
+    var _a2;
+    const location2 = sprite.currentLocation;
+    const altitude = (_a2 = location2.z) != null ? _a2 : 0;
+    if (sprite.cachedMercator && sprite.cachedMercatorLng === location2.lng && sprite.cachedMercatorLat === location2.lat && sprite.cachedMercatorZ === altitude) {
+      return sprite.cachedMercator;
+    }
+    const mercator = maplibreGlExports.MercatorCoordinate.fromLngLat(
+      { lng: location2.lng, lat: location2.lat },
+      altitude
+    );
+    sprite.cachedMercator = mercator;
+    sprite.cachedMercatorLng = location2.lng;
+    sprite.cachedMercatorLat = location2.lat;
+    sprite.cachedMercatorZ = altitude;
+    return mercator;
+  };
+  const HIT_TEST_WORLD_BOUNDS = {
+    x0: -180,
+    y0: -90,
+    x1: 180,
+    y1: 90
+  };
+  const hitTestTree = createLooseQuadTree({
+    bounds: HIT_TEST_WORLD_BOUNDS
+  });
+  let hitTestTreeItems = /* @__PURE__ */ new WeakMap();
+  let isHitTestEnabled = true;
+  const rectFromLngLatPoints = (points) => {
+    let minLng = Number.POSITIVE_INFINITY;
+    let maxLng = Number.NEGATIVE_INFINITY;
+    let minLat = Number.POSITIVE_INFINITY;
+    let maxLat = Number.NEGATIVE_INFINITY;
+    for (const point of points) {
+      if (!point || !Number.isFinite(point.lng) || !Number.isFinite(point.lat)) {
+        continue;
+      }
+      if (point.lng < minLng) minLng = point.lng;
+      if (point.lng > maxLng) maxLng = point.lng;
+      if (point.lat < minLat) minLat = point.lat;
+      if (point.lat > maxLat) maxLat = point.lat;
+    }
+    if (minLng === Number.POSITIVE_INFINITY || maxLng === Number.NEGATIVE_INFINITY || minLat === Number.POSITIVE_INFINITY || maxLat === Number.NEGATIVE_INFINITY) {
+      return null;
+    }
+    return {
+      x0: Math.max(
+        HIT_TEST_WORLD_BOUNDS.x0,
+        Math.min(minLng, HIT_TEST_WORLD_BOUNDS.x1)
+      ),
+      y0: Math.max(
+        HIT_TEST_WORLD_BOUNDS.y0,
+        Math.min(minLat, HIT_TEST_WORLD_BOUNDS.y1)
+      ),
+      x1: Math.max(
+        HIT_TEST_WORLD_BOUNDS.x0,
+        Math.min(maxLng, HIT_TEST_WORLD_BOUNDS.x1)
+      ),
+      y1: Math.max(
+        HIT_TEST_WORLD_BOUNDS.y0,
+        Math.min(maxLat, HIT_TEST_WORLD_BOUNDS.y1)
+      )
+    };
+  };
+  const rectFromRadiusMeters = (base, radiusMeters) => {
+    if (!Number.isFinite(base.lng) || !Number.isFinite(base.lat) || !Number.isFinite(radiusMeters) || radiusMeters <= 0) {
+      return null;
+    }
+    const cornerNE = applySurfaceDisplacement(
+      base.lng,
+      base.lat,
+      radiusMeters,
+      radiusMeters
+    );
+    const cornerSW = applySurfaceDisplacement(
+      base.lng,
+      base.lat,
+      -radiusMeters,
+      -radiusMeters
+    );
+    return rectFromLngLatPoints([cornerNE, cornerSW]);
+  };
+  const estimateSurfaceImageBounds = (sprite, image) => {
+    var _a2, _b, _c, _d, _e;
+    const mapInstance = map;
+    if (!mapInstance) {
+      return null;
+    }
+    const imageResource = images.get(image.imageId);
+    if (!imageResource) {
+      return null;
+    }
+    const baseLocation = sprite.currentLocation;
+    const zoom = mapInstance.getZoom();
+    const zoomScaleFactor = calculateZoomScaleFactor(zoom, resolvedScaling);
+    const metersPerPixelAtLat = calculateMetersPerPixelAtLatitude(
+      zoom,
+      baseLocation.lat
+    );
+    if (!Number.isFinite(metersPerPixelAtLat) || metersPerPixelAtLat <= 0) {
+      return null;
+    }
+    const spriteMercator = resolveSpriteMercator(sprite);
+    const perspectiveRatio = calculatePerspectiveRatio(
+      mapInstance,
+      baseLocation,
+      spriteMercator
+    );
+    const effectivePixelsPerMeter = calculateEffectivePixelsPerMeter(
+      metersPerPixelAtLat,
+      perspectiveRatio
+    );
+    if (!Number.isFinite(effectivePixelsPerMeter) || effectivePixelsPerMeter <= 0) {
+      return null;
+    }
+    const imageScale = (_a2 = image.scale) != null ? _a2 : 1;
+    const baseMetersPerPixel = resolvedScaling.metersPerPixel;
+    const spriteMinPixel = resolvedScaling.spriteMinPixel;
+    const spriteMaxPixel = resolvedScaling.spriteMaxPixel;
+    const worldDims = calculateSurfaceWorldDimensions(
+      imageResource.width,
+      imageResource.height,
+      baseMetersPerPixel,
+      imageScale,
+      zoomScaleFactor,
+      {
+        effectivePixelsPerMeter,
+        spriteMinPixel,
+        spriteMaxPixel
+      }
+    );
+    if (worldDims.width <= 0 || worldDims.height <= 0) {
+      return null;
+    }
+    const anchor = (_b = image.anchor) != null ? _b : DEFAULT_ANCHOR;
+    const offsetDef = (_c = image.offset) != null ? _c : DEFAULT_IMAGE_OFFSET;
+    const offsetMetersVec = calculateSurfaceOffsetMeters(
+      offsetDef,
+      imageScale,
+      zoomScaleFactor,
+      worldDims.scaleAdjustment
+    );
+    const totalRotateDeg = Number.isFinite(image.displayedRotateDeg) ? image.displayedRotateDeg : normalizeAngleDeg(
+      ((_d = image.resolvedBaseRotateDeg) != null ? _d : 0) + ((_e = image.rotateDeg) != null ? _e : 0)
+    );
+    const cornerDisplacements = calculateSurfaceCornerDisplacements({
+      worldWidthMeters: worldDims.width,
+      worldHeightMeters: worldDims.height,
+      anchor,
+      totalRotateDeg,
+      offsetMeters: offsetMetersVec
+    });
+    const corners = cornerDisplacements.map(
+      (corner) => applySurfaceDisplacement(
+        baseLocation.lng,
+        baseLocation.lat,
+        corner.east,
+        corner.north
+      )
+    );
+    return rectFromLngLatPoints(corners);
+  };
+  const estimateBillboardImageBounds = (sprite, image) => {
+    var _a2, _b, _c, _d;
+    const mapInstance = map;
+    if (!mapInstance) {
+      return null;
+    }
+    const imageResource = images.get(image.imageId);
+    if (!imageResource) {
+      return null;
+    }
+    const baseLocation = sprite.currentLocation;
+    const zoom = mapInstance.getZoom();
+    const zoomScaleFactor = calculateZoomScaleFactor(zoom, resolvedScaling);
+    const metersPerPixelAtLat = calculateMetersPerPixelAtLatitude(
+      zoom,
+      baseLocation.lat
+    );
+    if (!Number.isFinite(metersPerPixelAtLat) || metersPerPixelAtLat <= 0) {
+      return null;
+    }
+    const spriteMercator = resolveSpriteMercator(sprite);
+    const perspectiveRatio = calculatePerspectiveRatio(
+      mapInstance,
+      baseLocation,
+      spriteMercator
+    );
+    const effectivePixelsPerMeter = calculateEffectivePixelsPerMeter(
+      metersPerPixelAtLat,
+      perspectiveRatio
+    );
+    if (!Number.isFinite(effectivePixelsPerMeter) || effectivePixelsPerMeter <= 0) {
+      return null;
+    }
+    const baseMetersPerPixel = resolvedScaling.metersPerPixel;
+    const spriteMinPixel = resolvedScaling.spriteMinPixel;
+    const spriteMaxPixel = resolvedScaling.spriteMaxPixel;
+    const imageScale = (_a2 = image.scale) != null ? _a2 : 1;
+    const totalRotateDeg = Number.isFinite(image.displayedRotateDeg) ? image.displayedRotateDeg : normalizeAngleDeg(
+      ((_b = image.resolvedBaseRotateDeg) != null ? _b : 0) + ((_c = image.rotateDeg) != null ? _c : 0)
+    );
+    const pixelDims = calculateBillboardPixelDimensions(
+      imageResource.width,
+      imageResource.height,
+      baseMetersPerPixel,
+      imageScale,
+      zoomScaleFactor,
+      effectivePixelsPerMeter,
+      spriteMinPixel,
+      spriteMaxPixel
+    );
+    const halfWidthMeters = pixelDims.width / 2 / effectivePixelsPerMeter;
+    const halfHeightMeters = pixelDims.height / 2 / effectivePixelsPerMeter;
+    const anchorShift = calculateBillboardAnchorShiftPixels(
+      pixelDims.width / 2,
+      pixelDims.height / 2,
+      image.anchor,
+      totalRotateDeg
+    );
+    const offsetShift = calculateBillboardOffsetPixels(
+      (_d = image.offset) != null ? _d : DEFAULT_IMAGE_OFFSET,
+      imageScale,
+      zoomScaleFactor,
+      effectivePixelsPerMeter
+    );
+    const anchorShiftMeters = Math.hypot(anchorShift.x, anchorShift.y) / effectivePixelsPerMeter;
+    const offsetShiftMeters = Math.hypot(offsetShift.x, offsetShift.y) / effectivePixelsPerMeter;
+    const safetyRadius = Math.hypot(halfWidthMeters, halfHeightMeters) + anchorShiftMeters + offsetShiftMeters;
+    return rectFromRadiusMeters(baseLocation, safetyRadius);
+  };
+  const estimateImageBounds = (sprite, image) => {
+    if (image.opacity <= 0 || !sprite.isEnabled) {
+      return null;
+    }
+    if (image.mode === "surface") {
+      return estimateSurfaceImageBounds(sprite, image);
+    }
+    return estimateBillboardImageBounds(sprite, image);
+  };
+  const removeImageBoundsFromHitTestTree = (image) => {
+    const handle = hitTestTreeItems.get(image);
+    if (!handle) {
+      return;
+    }
+    hitTestTree.remove(
+      handle.rect.x0,
+      handle.rect.y0,
+      handle.rect.x1,
+      handle.rect.y1,
+      handle.item
+    );
+    hitTestTreeItems.delete(image);
+  };
+  const setItemRect = (item, rect) => {
+    const mutable = item;
+    mutable.x0 = rect.x0;
+    mutable.y0 = rect.y0;
+    mutable.x1 = rect.x1;
+    mutable.y1 = rect.y1;
   };
-  const cancelQueuedTextureUpload = (imageId) => {
-    queuedTextureIds.delete(imageId);
+  const registerImageBoundsInHitTestTree = (sprite, image) => {
+    const existingHandle = hitTestTreeItems.get(image);
+    if (!isHitTestEnabled) {
+      if (existingHandle) {
+        removeImageBoundsFromHitTestTree(image);
+      }
+      return;
+    }
+    const rect = estimateImageBounds(sprite, image);
+    if (!rect) {
+      if (existingHandle) {
+        removeImageBoundsFromHitTestTree(image);
+      }
+      return;
+    }
+    if (!existingHandle) {
+      const handle = {
+        rect,
+        item: {
+          x0: rect.x0,
+          y0: rect.y0,
+          x1: rect.x1,
+          y1: rect.y1,
+          state: {
+            sprite,
+            image,
+            drawIndex: 0
+          }
+        }
+      };
+      hitTestTree.add(handle.item);
+      hitTestTreeItems.set(image, handle);
+      return;
+    }
+    const currentRect = existingHandle.rect;
+    const unchanged = currentRect.x0 === rect.x0 && currentRect.y0 === rect.y0 && currentRect.x1 === rect.x1 && currentRect.y1 === rect.y1;
+    if (unchanged) {
+      return;
+    }
+    const updated = hitTestTree.update(
+      currentRect.x0,
+      currentRect.y0,
+      currentRect.x1,
+      currentRect.y1,
+      rect.x0,
+      rect.y0,
+      rect.x1,
+      rect.y1,
+      existingHandle.item
+    );
+    if (updated) {
+      existingHandle.rect = rect;
+      setItemRect(existingHandle.item, rect);
+      return;
+    }
+    removeImageBoundsFromHitTestTree(image);
+    const newHandle = {
+      rect,
+      item: {
+        x0: rect.x0,
+        y0: rect.y0,
+        x1: rect.x1,
+        y1: rect.y1,
+        state: {
+          sprite,
+          image,
+          drawIndex: 0
+        }
+      }
+    };
+    hitTestTree.add(newHandle.item);
+    hitTestTreeItems.set(image, newHandle);
   };
-  const clearTextureQueue = () => {
-    queuedTextureIds.clear();
+  const refreshSpriteHitTestBounds = (sprite) => {
+    sprite.images.forEach((orderMap) => {
+      orderMap.forEach((image) => {
+        registerImageBoundsInHitTestTree(sprite, image);
+      });
+    });
   };
-  const sprites = /* @__PURE__ */ new Map();
   const getImageState = (sprite, subLayer, order) => {
     var _a2;
     return (
@@ -23273,34 +24109,38 @@ const createSpriteLayer = (options) => {
     return deleted;
   };
   const HIT_TEST_EPSILON = 1e-3;
-  const pointInTriangle = (point, a, b, c) => {
-    const v0x = c.x - a.x;
-    const v0y = c.y - a.y;
-    const v1x = b.x - a.x;
-    const v1y = b.y - a.y;
-    const v2x = point.x - a.x;
-    const v2y = point.y - a.y;
-    const dot00 = v0x * v0x + v0y * v0y;
-    const dot01 = v0x * v1x + v0y * v1y;
-    const dot02 = v0x * v2x + v0y * v2y;
-    const dot11 = v1x * v1x + v1y * v1y;
-    const dot12 = v1x * v2x + v1y * v2y;
-    const denom = dot00 * dot11 - dot01 * dot01;
-    if (Math.abs(denom) < HIT_TEST_EPSILON) {
-      return false;
+  const pointInRenderedQuad = (point, corners) => {
+    let hasPositiveCross = false;
+    let hasNegativeCross = false;
+    for (let i = 0; i < DEBUG_OUTLINE_CORNER_ORDER.length; i++) {
+      const currentIndex = DEBUG_OUTLINE_CORNER_ORDER[i];
+      const nextIndex = DEBUG_OUTLINE_CORNER_ORDER[(i + 1) % DEBUG_OUTLINE_CORNER_ORDER.length];
+      const a = corners[currentIndex];
+      const b = corners[nextIndex];
+      const edgeX = b.x - a.x;
+      const edgeY = b.y - a.y;
+      const pointX = point.x - a.x;
+      const pointY = point.y - a.y;
+      const cross = edgeX * pointY - edgeY * pointX;
+      if (Math.abs(cross) <= HIT_TEST_EPSILON) {
+        continue;
+      }
+      if (cross > 0) {
+        hasPositiveCross = true;
+      } else {
+        hasNegativeCross = true;
+      }
+      if (hasPositiveCross && hasNegativeCross) {
+        return false;
+      }
     }
-    const invDenom = 1 / denom;
-    const u = (dot11 * dot02 - dot01 * dot12) * invDenom;
-    const v = (dot00 * dot12 - dot01 * dot02) * invDenom;
-    const w = 1 - u - v;
-    return u >= -HIT_TEST_EPSILON && v >= -HIT_TEST_EPSILON && w >= -HIT_TEST_EPSILON;
+    return true;
   };
-  const pointInQuad = (point, corners) => pointInTriangle(point, corners[0], corners[1], corners[2]) || pointInTriangle(point, corners[0], corners[2], corners[3]);
   const isPointInsideHitEntry = (entry, point) => {
     if (point.x < entry.minX - HIT_TEST_EPSILON || point.x > entry.maxX + HIT_TEST_EPSILON || point.y < entry.minY - HIT_TEST_EPSILON || point.y > entry.maxY + HIT_TEST_EPSILON) {
       return false;
     }
-    return pointInQuad(point, entry.corners);
+    return pointInRenderedQuad(point, entry.corners);
   };
   const buildSortedSubLayerBuckets = (entries) => {
     const buckets = /* @__PURE__ */ new Map();
@@ -23442,6 +24282,7 @@ const createSpriteLayer = (options) => {
   };
   const renderTargetEntries = [];
   const hitTestEntries = [];
+  let hitTestEntryByImage = /* @__PURE__ */ new WeakMap();
   const ensureHitTestCorners = (imageEntry) => {
     if (!imageEntry.hitTestCorners) {
       imageEntry.hitTestCorners = [
@@ -23453,7 +24294,10 @@ const createSpriteLayer = (options) => {
     }
     return imageEntry.hitTestCorners;
   };
-  const registerHitTestEntry = (spriteEntry, imageEntry, screenCorners) => {
+  const registerHitTestEntry = (spriteEntry, imageEntry, screenCorners, drawIndex) => {
+    if (!isHitTestEnabled) {
+      return;
+    }
     const corners = screenCorners;
     let minX = corners[0].x;
     let maxX = corners[0].x;
@@ -23466,7 +24310,7 @@ const createSpriteLayer = (options) => {
       if (corner.y < minY) minY = corner.y;
       if (corner.y > maxY) maxY = corner.y;
     }
-    hitTestEntries.push({
+    const entry = {
       sprite: spriteEntry,
       image: imageEntry,
       corners,
@@ -23474,9 +24318,15 @@ const createSpriteLayer = (options) => {
       maxX,
       minY,
       maxY
-    });
+    };
+    hitTestEntries.push(entry);
+    hitTestEntryByImage.set(imageEntry, entry);
+    const handle = hitTestTreeItems.get(imageEntry);
+    if (handle) {
+      handle.item.state.drawIndex = drawIndex;
+    }
   };
-  const findTopmostHitEntry = (point) => {
+  const findTopmostHitEntryLinear = (point) => {
     for (let i = hitTestEntries.length - 1; i >= 0; i--) {
       const entry = hitTestEntries[i];
       if (isPointInsideHitEntry(entry, point)) {
@@ -23485,6 +24335,66 @@ const createSpriteLayer = (options) => {
     }
     return null;
   };
+  const findTopmostHitEntry = (point) => {
+    if (!isHitTestEnabled) {
+      return null;
+    }
+    const mapInstance = map;
+    if (!mapInstance) {
+      return findTopmostHitEntryLinear(point);
+    }
+    const centerLngLat = mapInstance.unproject([point.x, point.y]);
+    if (!centerLngLat) {
+      return findTopmostHitEntryLinear(point);
+    }
+    const searchPoints = [
+      { lng: centerLngLat.lng, lat: centerLngLat.lat }
+    ];
+    const radius = HIT_TEST_QUERY_RADIUS_PIXELS;
+    const offsets = [
+      [point.x - radius, point.y - radius],
+      [point.x + radius, point.y - radius],
+      [point.x - radius, point.y + radius],
+      [point.x + radius, point.y + radius]
+    ];
+    for (const [x, y] of offsets) {
+      const lngLat = mapInstance.unproject([x, y]);
+      if (lngLat) {
+        searchPoints.push({ lng: lngLat.lng, lat: lngLat.lat });
+      }
+    }
+    const searchRect = rectFromLngLatPoints(searchPoints);
+    if (!searchRect) {
+      return findTopmostHitEntryLinear(point);
+    }
+    const candidates = hitTestTree.lookup(
+      searchRect.x0,
+      searchRect.y0,
+      searchRect.x1,
+      searchRect.y1
+    );
+    if (candidates.length === 0) {
+      return findTopmostHitEntryLinear(point);
+    }
+    candidates.sort((a, b) => a.state.drawIndex - b.state.drawIndex);
+    const seenImages = /* @__PURE__ */ new Set();
+    for (let i = candidates.length - 1; i >= 0; i--) {
+      const candidate = candidates[i];
+      const image = candidate.state.image;
+      if (seenImages.has(image)) {
+        continue;
+      }
+      seenImages.add(image);
+      const entry = hitTestEntryByImage.get(image);
+      if (!entry) {
+        continue;
+      }
+      if (isPointInsideHitEntry(entry, point)) {
+        return entry;
+      }
+    }
+    return findTopmostHitEntryLinear(point);
+  };
   const eventListeners = /* @__PURE__ */ new Map();
   const getListenerSet = (type) => {
     let set = eventListeners.get(type);
@@ -23867,7 +24777,59 @@ const createSpriteLayer = (options) => {
       shaderProgram,
       "u_opacity"
     );
-    if (!uniformTextureLocation || !uniformOpacityLocation) {
+    uniformScreenToClipScaleLocation = glContext.getUniformLocation(
+      shaderProgram,
+      "u_screenToClipScale"
+    );
+    uniformScreenToClipOffsetLocation = glContext.getUniformLocation(
+      shaderProgram,
+      "u_screenToClipOffset"
+    );
+    uniformBillboardModeLocation = glContext.getUniformLocation(
+      shaderProgram,
+      "u_billboardMode"
+    );
+    uniformBillboardCenterLocation = glContext.getUniformLocation(
+      shaderProgram,
+      "u_billboardCenter"
+    );
+    uniformBillboardHalfSizeLocation = glContext.getUniformLocation(
+      shaderProgram,
+      "u_billboardHalfSize"
+    );
+    uniformBillboardAnchorLocation = glContext.getUniformLocation(
+      shaderProgram,
+      "u_billboardAnchor"
+    );
+    uniformBillboardSinCosLocation = glContext.getUniformLocation(
+      shaderProgram,
+      "u_billboardSinCos"
+    );
+    uniformSurfaceModeLocation = glContext.getUniformLocation(
+      shaderProgram,
+      "u_surfaceMode"
+    );
+    uniformSurfaceDepthBiasLocation = glContext.getUniformLocation(
+      shaderProgram,
+      "u_surfaceDepthBias"
+    );
+    uniformSurfaceClipEnabledLocation = glContext.getUniformLocation(
+      shaderProgram,
+      "u_surfaceClipEnabled"
+    );
+    uniformSurfaceClipCenterLocation = glContext.getUniformLocation(
+      shaderProgram,
+      "u_surfaceClipCenter"
+    );
+    uniformSurfaceClipBasisEastLocation = glContext.getUniformLocation(
+      shaderProgram,
+      "u_surfaceClipBasisEast"
+    );
+    uniformSurfaceClipBasisNorthLocation = glContext.getUniformLocation(
+      shaderProgram,
+      "u_surfaceClipBasisNorth"
+    );
+    if (!uniformTextureLocation || !uniformOpacityLocation || !uniformScreenToClipScaleLocation || !uniformScreenToClipOffsetLocation || !uniformBillboardModeLocation || !uniformBillboardCenterLocation || !uniformBillboardHalfSizeLocation || !uniformBillboardAnchorLocation || !uniformBillboardSinCosLocation || !uniformSurfaceModeLocation || !uniformSurfaceDepthBiasLocation || !uniformSurfaceClipEnabledLocation || !uniformSurfaceClipCenterLocation || !uniformSurfaceClipBasisEastLocation || !uniformSurfaceClipBasisNorthLocation) {
       throw new Error("Failed to acquire uniform locations.");
     }
     glContext.enableVertexAttribArray(attribPositionLocation);
@@ -23890,7 +24852,80 @@ const createSpriteLayer = (options) => {
     );
     glContext.uniform1i(uniformTextureLocation, 0);
     glContext.uniform1f(uniformOpacityLocation, 1);
+    glContext.uniform2f(uniformScreenToClipScaleLocation, 1, 1);
+    glContext.uniform2f(uniformScreenToClipOffsetLocation, 0, 0);
+    glContext.uniform1f(uniformSurfaceClipEnabledLocation, 0);
+    glContext.uniform4f(uniformSurfaceClipCenterLocation, 0, 0, 0, 1);
+    glContext.uniform4f(
+      uniformSurfaceClipBasisEastLocation,
+      0,
+      0,
+      0,
+      0
+    );
+    glContext.uniform4f(
+      uniformSurfaceClipBasisNorthLocation,
+      0,
+      0,
+      0,
+      0
+    );
+    glContext.uniform1f(uniformBillboardModeLocation, 0);
+    glContext.uniform2f(uniformBillboardCenterLocation, 0, 0);
+    glContext.uniform2f(uniformBillboardHalfSizeLocation, 0, 0);
+    glContext.uniform2f(uniformBillboardAnchorLocation, 0, 0);
+    glContext.uniform2f(uniformBillboardSinCosLocation, 0, 1);
+    glContext.uniform1f(uniformSurfaceModeLocation, 0);
+    glContext.uniform1f(uniformSurfaceDepthBiasLocation, 0);
     glContext.bindBuffer(glContext.ARRAY_BUFFER, null);
+    if (showDebugBounds) {
+      const debugShaderProgram = createShaderProgram(
+        glContext,
+        DEBUG_OUTLINE_VERTEX_SHADER_SOURCE,
+        DEBUG_OUTLINE_FRAGMENT_SHADER_SOURCE
+      );
+      debugProgram = debugShaderProgram;
+      debugAttribPositionLocation = glContext.getAttribLocation(
+        debugShaderProgram,
+        "a_position"
+      );
+      if (debugAttribPositionLocation === -1) {
+        throw new Error("Failed to acquire debug attribute location.");
+      }
+      const colorLocation = glContext.getUniformLocation(
+        debugShaderProgram,
+        "u_color"
+      );
+      if (!colorLocation) {
+        throw new Error("Failed to acquire debug color uniform.");
+      }
+      debugUniformColorLocation = colorLocation;
+      debugUniformScreenToClipScaleLocation = glContext.getUniformLocation(
+        debugShaderProgram,
+        "u_screenToClipScale"
+      );
+      debugUniformScreenToClipOffsetLocation = glContext.getUniformLocation(
+        debugShaderProgram,
+        "u_screenToClipOffset"
+      );
+      if (!debugUniformScreenToClipScaleLocation || !debugUniformScreenToClipOffsetLocation) {
+        throw new Error("Failed to acquire debug screen-to-clip uniforms.");
+      }
+      glContext.uniform2f(debugUniformScreenToClipScaleLocation, 1, 1);
+      glContext.uniform2f(debugUniformScreenToClipOffsetLocation, 0, 0);
+      const outlineBuffer = glContext.createBuffer();
+      if (!outlineBuffer) {
+        throw new Error("Failed to create debug vertex buffer.");
+      }
+      debugVertexBuffer = outlineBuffer;
+      glContext.bindBuffer(glContext.ARRAY_BUFFER, outlineBuffer);
+      glContext.bufferData(
+        glContext.ARRAY_BUFFER,
+        DEBUG_OUTLINE_VERTEX_SCRATCH,
+        glContext.DYNAMIC_DRAW
+      );
+      glContext.bindBuffer(glContext.ARRAY_BUFFER, null);
+    }
     scheduleRender();
   };
   const onRemove = () => {
@@ -23898,6 +24933,9 @@ const createSpriteLayer = (options) => {
     inputListenerDisposers.length = 0;
     canvasElement = null;
     hitTestEntries.length = 0;
+    hitTestEntryByImage = /* @__PURE__ */ new WeakMap();
+    hitTestTree.clear();
+    hitTestTreeItems = /* @__PURE__ */ new WeakMap();
     const glContext = gl;
     if (glContext) {
       images.forEach((image) => {
@@ -23910,9 +24948,15 @@ const createSpriteLayer = (options) => {
       if (vertexBuffer) {
         glContext.deleteBuffer(vertexBuffer);
       }
+      if (debugVertexBuffer) {
+        glContext.deleteBuffer(debugVertexBuffer);
+      }
       if (program) {
         glContext.deleteProgram(program);
       }
+      if (debugProgram) {
+        glContext.deleteProgram(debugProgram);
+      }
     }
     eventListeners.forEach((set) => set.clear());
     eventListeners.clear();
@@ -23920,20 +24964,36 @@ const createSpriteLayer = (options) => {
     map = null;
     program = null;
     vertexBuffer = null;
+    debugProgram = null;
+    debugVertexBuffer = null;
     attribPositionLocation = -1;
     attribUvLocation = -1;
+    debugAttribPositionLocation = -1;
     uniformTextureLocation = null;
     uniformOpacityLocation = null;
+    uniformScreenToClipScaleLocation = null;
+    uniformScreenToClipOffsetLocation = null;
+    uniformBillboardModeLocation = null;
+    uniformBillboardCenterLocation = null;
+    uniformBillboardHalfSizeLocation = null;
+    uniformBillboardAnchorLocation = null;
+    uniformBillboardSinCosLocation = null;
+    uniformSurfaceModeLocation = null;
+    uniformSurfaceDepthBiasLocation = null;
+    debugUniformColorLocation = null;
+    debugUniformScreenToClipScaleLocation = null;
+    debugUniformScreenToClipOffsetLocation = null;
     anisotropyExtension = null;
     maxSupportedAnisotropy = 1;
   };
   const render = (glContext, _options) => {
     hitTestEntries.length = 0;
+    hitTestEntryByImage = /* @__PURE__ */ new WeakMap();
     const mapInstance = map;
     if (!mapInstance || !program || !vertexBuffer) {
       return;
     }
-    if (!uniformOpacityLocation || !uniformTextureLocation) {
+    if (!uniformOpacityLocation || !uniformTextureLocation || !uniformScreenToClipScaleLocation || !uniformScreenToClipOffsetLocation) {
       return;
     }
     const timestamp = typeof performance !== "undefined" && typeof performance.now === "function" ? (
@@ -23985,6 +25045,17 @@ const createSpriteLayer = (options) => {
     const drawingBufferWidth = glContext.drawingBufferWidth;
     const drawingBufferHeight = glContext.drawingBufferHeight;
     const pixelRatio = drawingBufferWidth / cssWidth;
+    if (drawingBufferWidth === 0 || drawingBufferHeight === 0) {
+      return;
+    }
+    const screenToClipScaleX = 2 * pixelRatio / drawingBufferWidth;
+    const screenToClipScaleY = -2 * pixelRatio / drawingBufferHeight;
+    const screenToClipOffsetX = -1;
+    const screenToClipOffsetY = 1;
+    const identityScaleX = 1;
+    const identityScaleY = 1;
+    const identityOffsetX = 0;
+    const identityOffsetY = 0;
     const zoom = mapInstance.getZoom();
     const zoomScaleFactor = calculateZoomScaleFactor(zoom, resolvedScaling);
     const baseMetersPerPixel = resolvedScaling.metersPerPixel;
@@ -24019,11 +25090,76 @@ const createSpriteLayer = (options) => {
       UV_OFFSET
     );
     glContext.uniform1i(uniformTextureLocation, 0);
+    const screenToClipScaleLocation = uniformScreenToClipScaleLocation;
+    const screenToClipOffsetLocation = uniformScreenToClipOffsetLocation;
+    let currentScaleX = Number.NaN;
+    let currentScaleY = Number.NaN;
+    let currentOffsetX = Number.NaN;
+    let currentOffsetY = Number.NaN;
+    const applyScreenToClipUniforms = (scaleX, scaleY, offsetX, offsetY) => {
+      if (scaleX !== currentScaleX || scaleY !== currentScaleY || offsetX !== currentOffsetX || offsetY !== currentOffsetY) {
+        glContext.uniform2f(screenToClipScaleLocation, scaleX, scaleY);
+        glContext.uniform2f(screenToClipOffsetLocation, offsetX, offsetY);
+        currentScaleX = scaleX;
+        currentScaleY = scaleY;
+        currentOffsetX = offsetX;
+        currentOffsetY = offsetY;
+      }
+    };
+    let currentSurfaceMode = Number.NaN;
+    const applySurfaceMode = (enabled) => {
+      if (!uniformSurfaceModeLocation) {
+        return;
+      }
+      const value = enabled ? 1 : 0;
+      if (value !== currentSurfaceMode) {
+        glContext.uniform1f(uniformSurfaceModeLocation, value);
+        currentSurfaceMode = value;
+      }
+    };
+    let currentSurfaceClipEnabled = Number.NaN;
+    const applySurfaceClipUniforms = (enabled, inputs) => {
+      if (!uniformSurfaceClipEnabledLocation || !uniformSurfaceClipCenterLocation || !uniformSurfaceClipBasisEastLocation || !uniformSurfaceClipBasisNorthLocation) {
+        return;
+      }
+      const value = enabled ? 1 : 0;
+      if (value !== currentSurfaceClipEnabled) {
+        glContext.uniform1f(uniformSurfaceClipEnabledLocation, value);
+        currentSurfaceClipEnabled = value;
+      }
+      const clipCenter = enabled && inputs ? inputs.clipCenter : { x: 0, y: 0, z: 0, w: 1 };
+      glContext.uniform4f(
+        uniformSurfaceClipCenterLocation,
+        clipCenter.x,
+        clipCenter.y,
+        clipCenter.z,
+        clipCenter.w
+      );
+      const clipBasisEast = enabled && inputs ? inputs.clipBasisEast : { x: 0, y: 0, z: 0, w: 0 };
+      glContext.uniform4f(
+        uniformSurfaceClipBasisEastLocation,
+        clipBasisEast.x,
+        clipBasisEast.y,
+        clipBasisEast.z,
+        clipBasisEast.w
+      );
+      const clipBasisNorth = enabled && inputs ? inputs.clipBasisNorth : { x: 0, y: 0, z: 0, w: 0 };
+      glContext.uniform4f(
+        uniformSurfaceClipBasisNorthLocation,
+        clipBasisNorth.x,
+        clipBasisNorth.y,
+        clipBasisNorth.z,
+        clipBasisNorth.w
+      );
+    };
+    let drawOrderCounter = 0;
     const drawSpriteImage = (spriteEntry, imageEntry, imageResource, originCenterCache2) => {
-      var _a2, _b, _c, _d, _e, _f, _g, _h, _i, _j;
+      var _a2, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n;
       let screenCornerBuffer = null;
       const anchor = (_a2 = imageEntry.anchor) != null ? _a2 : DEFAULT_ANCHOR;
       const offsetDef = (_b = imageEntry.offset) != null ? _b : DEFAULT_IMAGE_OFFSET;
+      applySurfaceMode(false);
+      applySurfaceClipUniforms(false, null);
       const totalRotateDeg = Number.isFinite(imageEntry.displayedRotateDeg) ? imageEntry.displayedRotateDeg : normalizeAngleDeg(
         ((_c = imageEntry.resolvedBaseRotateDeg) != null ? _c : 0) + ((_d = imageEntry.rotateDeg) != null ? _d : 0)
       );
@@ -24031,6 +25167,7 @@ const createSpriteLayer = (options) => {
       if (!projected) {
         return;
       }
+      const spriteMercator = resolveSpriteMercator(spriteEntry);
       const metersPerPixelAtLat = calculateMetersPerPixelAtLatitude(
         zoom,
         spriteEntry.currentLocation.lat
@@ -24040,7 +25177,8 @@ const createSpriteLayer = (options) => {
       }
       const perspectiveRatio = calculatePerspectiveRatio(
         mapInstance,
-        spriteEntry.currentLocation
+        spriteEntry.currentLocation,
+        spriteMercator
       );
       const effectivePixelsPerMeter = calculateEffectivePixelsPerMeter(
         metersPerPixelAtLat,
@@ -24050,6 +25188,7 @@ const createSpriteLayer = (options) => {
         return;
       }
       const imageScale = (_e = imageEntry.scale) != null ? _e : 1;
+      const altitudeMeters = (_f = spriteEntry.currentLocation.z) != null ? _f : 0;
       const centerParams = {
         mapInstance,
         images,
@@ -24064,7 +25203,7 @@ const createSpriteLayer = (options) => {
         drawingBufferHeight,
         pixelRatio,
         clipContext,
-        altitudeMeters: (_f = spriteEntry.currentLocation.z) != null ? _f : 0
+        altitudeMeters
       };
       let baseProjected = { x: projected.x, y: projected.y };
       if (imageEntry.originLocation !== void 0) {
@@ -24081,6 +25220,13 @@ const createSpriteLayer = (options) => {
         }
       }
       if (imageEntry.mode === "surface") {
+        applyScreenToClipUniforms(
+          identityScaleX,
+          identityScaleY,
+          identityOffsetX,
+          identityOffsetY
+        );
+        imageEntry.surfaceShaderInputs = void 0;
         const baseLngLat = imageEntry.originLocation !== void 0 ? (
           // When an origin reference is set, reproject the cached screen point back to geographic space.
           mapInstance.unproject([
@@ -24108,7 +25254,7 @@ const createSpriteLayer = (options) => {
           drawingBufferWidth,
           drawingBufferHeight,
           pixelRatio,
-          altitudeMeters: (_i = spriteEntry.currentLocation.z) != null ? _i : 0,
+          altitudeMeters,
           project: !clipContext ? (lngLat) => {
             const result = mapInstance.project(lngLat);
             return result ? { x: result.x, y: result.y } : null;
@@ -24117,6 +25263,9 @@ const createSpriteLayer = (options) => {
         if (!surfaceCenter.center) {
           return;
         }
+        if (uniformBillboardModeLocation) {
+          glContext.uniform1f(uniformBillboardModeLocation, 0);
+        }
         const offsetMeters = calculateSurfaceOffsetMeters(
           offsetDef,
           imageScale,
@@ -24130,6 +25279,51 @@ const createSpriteLayer = (options) => {
           totalRotateDeg,
           offsetMeters
         });
+        const orderIndex = Math.min(imageEntry.order, ORDER_MAX - 1);
+        const depthBiasNdc = -((imageEntry.subLayer * ORDER_BUCKET + orderIndex) * EPS_NDC);
+        const displacedCenterLngLat = (_i = surfaceCenter.displacedLngLat) != null ? _i : baseLngLat;
+        const displacedCenter = {
+          lng: displacedCenterLngLat.lng,
+          lat: displacedCenterLngLat.lat,
+          z: altitudeMeters
+        };
+        const surfaceShaderInputs = prepareSurfaceShaderInputs({
+          baseLngLat,
+          worldWidthMeters: surfaceCenter.worldDimensions.width,
+          worldHeightMeters: surfaceCenter.worldDimensions.height,
+          anchor,
+          totalRotateDeg,
+          offsetMeters,
+          displacedCenter,
+          altitudeMeters,
+          depthBiasNdc,
+          scaleAdjustment: surfaceCenter.worldDimensions.scaleAdjustment,
+          centerDisplacement: surfaceCenter.totalDisplacement
+        });
+        imageEntry.surfaceShaderInputs = surfaceShaderInputs;
+        let useShaderSurface = !!clipContext;
+        let clipCornerPositions = null;
+        let clipCenterPosition = null;
+        if (useShaderSurface) {
+          clipCornerPositions = new Array(SURFACE_BASE_CORNERS.length);
+          clipCenterPosition = projectLngLatToClipSpace(
+            displacedCenter.lng,
+            displacedCenter.lat,
+            (_j = displacedCenter.z) != null ? _j : altitudeMeters,
+            clipContext
+          );
+          if (!clipCenterPosition) {
+            useShaderSurface = false;
+            clipCornerPositions = null;
+          }
+        }
+        applySurfaceMode(useShaderSurface);
+        if (useShaderSurface && uniformSurfaceDepthBiasLocation) {
+          glContext.uniform1f(
+            uniformSurfaceDepthBiasLocation,
+            surfaceShaderInputs.depthBiasNdc
+          );
+        }
         const hitTestCorners = ensureHitTestCorners(imageEntry);
         let bufferOffset = 0;
         for (const index of TRIANGLE_INDICES) {
@@ -24143,46 +25337,145 @@ const createSpriteLayer = (options) => {
           const clipPosition = projectLngLatToClipSpace(
             displaced.lng,
             displaced.lat,
-            // Default altitude to zero when sprites lack explicit elevation.
-            (_j = spriteEntry.currentLocation.z) != null ? _j : 0,
+            altitudeMeters,
             clipContext
           );
           if (!clipPosition) {
             return;
           }
-          const screenCorner = clipToScreen(
-            clipPosition,
-            drawingBufferWidth,
-            drawingBufferHeight,
-            pixelRatio
-          );
-          if (!screenCorner) {
-            return;
-          }
-          const targetCorner = hitTestCorners[index];
-          targetCorner.x = screenCorner.x;
-          targetCorner.y = screenCorner.y;
           let [clipX, clipY, clipZ, clipW] = clipPosition;
-          {
-            const orderIndex = Math.min(imageEntry.order, ORDER_MAX - 1);
-            const biasIndex = imageEntry.subLayer * ORDER_BUCKET + orderIndex;
-            const biasNdc = -(biasIndex * EPS_NDC);
-            clipZ += biasNdc * clipW;
+          if (!useShaderSurface) {
+            const screenCorner = clipToScreen(
+              clipPosition,
+              drawingBufferWidth,
+              drawingBufferHeight,
+              pixelRatio
+            );
+            if (!screenCorner) {
+              return;
+            }
+            const targetCorner = hitTestCorners[index];
+            targetCorner.x = screenCorner.x;
+            targetCorner.y = screenCorner.y;
+          }
+          if (depthBiasNdc !== 0) {
+            clipZ += depthBiasNdc * clipW;
             const minClipZ = -clipW + MIN_CLIP_Z_EPSILON;
             if (clipZ < minClipZ) {
               clipZ = minClipZ;
             }
           }
+          if (clipCornerPositions) {
+            clipCornerPositions[index] = [clipX, clipY, clipZ, clipW];
+          }
           const [u, v] = UV_CORNERS[index];
-          QUAD_VERTEX_SCRATCH[bufferOffset++] = clipX;
-          QUAD_VERTEX_SCRATCH[bufferOffset++] = clipY;
-          QUAD_VERTEX_SCRATCH[bufferOffset++] = clipZ;
-          QUAD_VERTEX_SCRATCH[bufferOffset++] = clipW;
+          if (useShaderSurface) {
+            const baseCorner = SURFACE_BASE_CORNERS[index];
+            QUAD_VERTEX_SCRATCH[bufferOffset++] = baseCorner[0];
+            QUAD_VERTEX_SCRATCH[bufferOffset++] = baseCorner[1];
+            QUAD_VERTEX_SCRATCH[bufferOffset++] = 0;
+            QUAD_VERTEX_SCRATCH[bufferOffset++] = 1;
+          } else {
+            QUAD_VERTEX_SCRATCH[bufferOffset++] = clipX;
+            QUAD_VERTEX_SCRATCH[bufferOffset++] = clipY;
+            QUAD_VERTEX_SCRATCH[bufferOffset++] = clipZ;
+            QUAD_VERTEX_SCRATCH[bufferOffset++] = clipW;
+          }
           QUAD_VERTEX_SCRATCH[bufferOffset++] = u;
           QUAD_VERTEX_SCRATCH[bufferOffset++] = v;
         }
+        let clipUniformEnabled = false;
+        if (clipCornerPositions && clipCenterPosition && clipCornerPositions.every((corner) => Array.isArray(corner))) {
+          const leftTop = clipCornerPositions[0];
+          const rightTop = clipCornerPositions[1];
+          const leftBottom = clipCornerPositions[2];
+          const rightBottom = clipCornerPositions[3];
+          if (leftTop && rightTop && leftBottom && rightBottom) {
+            const clipBasisEast = [
+              (rightTop[0] - leftTop[0]) * 0.5,
+              (rightTop[1] - leftTop[1]) * 0.5,
+              (rightTop[2] - leftTop[2]) * 0.5,
+              (rightTop[3] - leftTop[3]) * 0.5
+            ];
+            const clipBasisNorth = [
+              (leftTop[0] - leftBottom[0]) * 0.5,
+              (leftTop[1] - leftBottom[1]) * 0.5,
+              (leftTop[2] - leftBottom[2]) * 0.5,
+              (leftTop[3] - leftBottom[3]) * 0.5
+            ];
+            surfaceShaderInputs.clipCenter = {
+              x: clipCenterPosition[0],
+              y: clipCenterPosition[1],
+              z: clipCenterPosition[2],
+              w: clipCenterPosition[3]
+            };
+            surfaceShaderInputs.clipBasisEast = {
+              x: clipBasisEast[0],
+              y: clipBasisEast[1],
+              z: clipBasisEast[2],
+              w: clipBasisEast[3]
+            };
+            surfaceShaderInputs.clipBasisNorth = {
+              x: clipBasisNorth[0],
+              y: clipBasisNorth[1],
+              z: clipBasisNorth[2],
+              w: clipBasisNorth[3]
+            };
+            const clipCornersForInputs = [];
+            let allCornersResolved = true;
+            for (let cornerIndex = 0; cornerIndex < SURFACE_BASE_CORNERS.length; cornerIndex++) {
+              const clipCorner = clipCornerPositions[cornerIndex];
+              if (!clipCorner) {
+                allCornersResolved = false;
+                break;
+              }
+              clipCornersForInputs.push({
+                x: clipCorner[0],
+                y: clipCorner[1],
+                z: clipCorner[2],
+                w: clipCorner[3]
+              });
+              const screenCorner = clipToScreen(
+                clipCorner,
+                drawingBufferWidth,
+                drawingBufferHeight,
+                pixelRatio
+              );
+              if (!screenCorner) {
+                return;
+              }
+              const targetCorner = hitTestCorners[cornerIndex];
+              targetCorner.x = screenCorner.x;
+              targetCorner.y = screenCorner.y;
+            }
+            if (allCornersResolved) {
+              surfaceShaderInputs.clipCorners = clipCornersForInputs;
+              clipUniformEnabled = true;
+            } else {
+              surfaceShaderInputs.clipCorners = [];
+            }
+          }
+        } else {
+          surfaceShaderInputs.clipCorners = [];
+        }
+        if (useShaderSurface) {
+          applySurfaceClipUniforms(
+            clipUniformEnabled,
+            clipUniformEnabled ? surfaceShaderInputs : null
+          );
+        } else {
+          applySurfaceClipUniforms(false, null);
+        }
         screenCornerBuffer = hitTestCorners;
       } else {
+        applyScreenToClipUniforms(
+          screenToClipScaleX,
+          screenToClipScaleY,
+          screenToClipOffsetX,
+          screenToClipOffsetY
+        );
+        imageEntry.surfaceShaderInputs = void 0;
+        applySurfaceMode(false);
         const placement = calculateBillboardCenterPosition({
           base: baseProjected,
           imageWidth: imageResource.width,
@@ -24197,46 +25490,95 @@ const createSpriteLayer = (options) => {
           anchor,
           offset: offsetDef
         });
-        const corners = calculateBillboardCornerScreenPositions({
+        const billboardShaderInputs = {
           centerX: placement.centerX,
           centerY: placement.centerY,
           halfWidth: placement.halfWidth,
           halfHeight: placement.halfHeight,
           anchor,
           totalRotateDeg
-        });
-        const hitTestCorners = ensureHitTestCorners(imageEntry);
-        let bufferOffset = 0;
-        for (const index of TRIANGLE_INDICES) {
-          const corner = corners[index];
-          const [clipX, clipY] = screenToClip(
-            corner.x,
-            corner.y,
-            drawingBufferWidth,
-            drawingBufferHeight,
-            pixelRatio
+        };
+        if (uniformBillboardModeLocation) {
+          glContext.uniform1f(
+            uniformBillboardModeLocation,
+            1
           );
-          QUAD_VERTEX_SCRATCH[bufferOffset++] = clipX;
-          QUAD_VERTEX_SCRATCH[bufferOffset++] = clipY;
-          QUAD_VERTEX_SCRATCH[bufferOffset++] = 0;
-          QUAD_VERTEX_SCRATCH[bufferOffset++] = 1;
-          QUAD_VERTEX_SCRATCH[bufferOffset++] = corner.u;
-          QUAD_VERTEX_SCRATCH[bufferOffset++] = corner.v;
-        }
-        for (let i = 0; i < corners.length; i++) {
-          const source = corners[i];
-          const target = hitTestCorners[i];
-          target.x = source.x;
-          target.y = source.y;
         }
-        screenCornerBuffer = hitTestCorners;
+        const writeBillboardCorners = (corners, useShaderGeometry) => {
+          const hitTestCorners = ensureHitTestCorners(imageEntry);
+          let bufferOffset = 0;
+          for (const index of TRIANGLE_INDICES) {
+            const corner = corners[index];
+            {
+              const baseCorner = BILLBOARD_BASE_CORNERS[index];
+              QUAD_VERTEX_SCRATCH[bufferOffset++] = baseCorner[0];
+              QUAD_VERTEX_SCRATCH[bufferOffset++] = baseCorner[1];
+            }
+            QUAD_VERTEX_SCRATCH[bufferOffset++] = 0;
+            QUAD_VERTEX_SCRATCH[bufferOffset++] = 1;
+            QUAD_VERTEX_SCRATCH[bufferOffset++] = corner.u;
+            QUAD_VERTEX_SCRATCH[bufferOffset++] = corner.v;
+          }
+          for (let i = 0; i < corners.length; i++) {
+            const source = corners[i];
+            const target = hitTestCorners[i];
+            target.x = source.x;
+            target.y = source.y;
+          }
+          screenCornerBuffer = hitTestCorners;
+        };
+        let resolvedCorners;
+        let shaderModelCorners;
+        {
+          if (uniformBillboardCenterLocation) {
+            glContext.uniform2f(
+              uniformBillboardCenterLocation,
+              billboardShaderInputs.centerX,
+              billboardShaderInputs.centerY
+            );
+          }
+          if (uniformBillboardHalfSizeLocation) {
+            glContext.uniform2f(
+              uniformBillboardHalfSizeLocation,
+              billboardShaderInputs.halfWidth,
+              billboardShaderInputs.halfHeight
+            );
+          }
+          if (uniformBillboardAnchorLocation) {
+            glContext.uniform2f(
+              uniformBillboardAnchorLocation,
+              (_l = (_k = billboardShaderInputs.anchor) == null ? void 0 : _k.x) != null ? _l : 0,
+              (_n = (_m = billboardShaderInputs.anchor) == null ? void 0 : _m.y) != null ? _n : 0
+            );
+          }
+          if (uniformBillboardSinCosLocation) {
+            const rad = -billboardShaderInputs.totalRotateDeg * DEG2RAD;
+            glContext.uniform2f(
+              uniformBillboardSinCosLocation,
+              Math.sin(rad),
+              Math.cos(rad)
+            );
+          }
+          shaderModelCorners = computeBillboardCornersShaderModel({
+            centerX: billboardShaderInputs.centerX,
+            centerY: billboardShaderInputs.centerY,
+            halfWidth: billboardShaderInputs.halfWidth,
+            halfHeight: billboardShaderInputs.halfHeight,
+            anchor: billboardShaderInputs.anchor,
+            rotationDeg: billboardShaderInputs.totalRotateDeg
+          });
+          resolvedCorners = shaderModelCorners;
+        }
+        writeBillboardCorners(resolvedCorners);
       }
       if (screenCornerBuffer && screenCornerBuffer.length === 4) {
         registerHitTestEntry(
           spriteEntry,
           imageEntry,
-          screenCornerBuffer
+          screenCornerBuffer,
+          drawOrderCounter
         );
+        drawOrderCounter += 1;
       }
       glContext.bufferSubData(glContext.ARRAY_BUFFER, 0, QUAD_VERTEX_SCRATCH);
       glContext.uniform1f(uniformOpacityLocation, imageEntry.opacity);
@@ -24266,6 +25608,7 @@ const createSpriteLayer = (options) => {
         if (!projected) {
           continue;
         }
+        const spriteMercator = resolveSpriteMercator(spriteEntry);
         const metersPerPixelAtLat = calculateMetersPerPixelAtLatitude(
           zoom,
           spriteEntry.currentLocation.lat
@@ -24275,7 +25618,8 @@ const createSpriteLayer = (options) => {
         }
         const perspectiveRatio = calculatePerspectiveRatio(
           mapInstance,
-          spriteEntry.currentLocation
+          spriteEntry.currentLocation,
+          spriteMercator
         );
         const effectivePixelsPerMeter = calculateEffectivePixelsPerMeter(
           metersPerPixelAtLat,
@@ -24438,6 +25782,64 @@ const createSpriteLayer = (options) => {
     for (const [, bucket] of sortedSubLayerBuckets) {
       renderSortedBucket(bucket);
     }
+    if (showDebugBounds && debugProgram && debugVertexBuffer && debugUniformColorLocation && debugAttribPositionLocation !== -1) {
+      glContext.useProgram(debugProgram);
+      glContext.bindBuffer(glContext.ARRAY_BUFFER, debugVertexBuffer);
+      glContext.enableVertexAttribArray(debugAttribPositionLocation);
+      glContext.vertexAttribPointer(
+        debugAttribPositionLocation,
+        DEBUG_OUTLINE_POSITION_COMPONENT_COUNT,
+        glContext.FLOAT,
+        false,
+        DEBUG_OUTLINE_VERTEX_STRIDE,
+        0
+      );
+      glContext.disable(glContext.DEPTH_TEST);
+      glContext.depthMask(false);
+      glContext.uniform4f(
+        debugUniformColorLocation,
+        DEBUG_OUTLINE_COLOR[0],
+        DEBUG_OUTLINE_COLOR[1],
+        DEBUG_OUTLINE_COLOR[2],
+        DEBUG_OUTLINE_COLOR[3]
+      );
+      if (debugUniformScreenToClipScaleLocation && debugUniformScreenToClipOffsetLocation) {
+        glContext.uniform2f(
+          debugUniformScreenToClipScaleLocation,
+          screenToClipScaleX,
+          screenToClipScaleY
+        );
+        glContext.uniform2f(
+          debugUniformScreenToClipOffsetLocation,
+          screenToClipOffsetX,
+          screenToClipOffsetY
+        );
+      }
+      for (const entry of hitTestEntries) {
+        let writeOffset = 0;
+        for (const cornerIndex of DEBUG_OUTLINE_CORNER_ORDER) {
+          const corner = entry.corners[cornerIndex];
+          DEBUG_OUTLINE_VERTEX_SCRATCH[writeOffset++] = corner.x;
+          DEBUG_OUTLINE_VERTEX_SCRATCH[writeOffset++] = corner.y;
+          DEBUG_OUTLINE_VERTEX_SCRATCH[writeOffset++] = 0;
+          DEBUG_OUTLINE_VERTEX_SCRATCH[writeOffset++] = 1;
+        }
+        glContext.bufferSubData(
+          glContext.ARRAY_BUFFER,
+          0,
+          DEBUG_OUTLINE_VERTEX_SCRATCH
+        );
+        glContext.drawArrays(
+          glContext.LINE_LOOP,
+          0,
+          DEBUG_OUTLINE_VERTEX_COUNT
+        );
+      }
+      glContext.depthMask(true);
+      glContext.enable(glContext.DEPTH_TEST);
+      glContext.disableVertexAttribArray(debugAttribPositionLocation);
+      glContext.bindBuffer(glContext.ARRAY_BUFFER, null);
+    }
     glContext.depthMask(true);
     glContext.enable(glContext.DEPTH_TEST);
     glContext.disable(glContext.BLEND);
@@ -24673,6 +26075,15 @@ const createSpriteLayer = (options) => {
     if (!image) {
       return false;
     }
+    sprites.forEach((sprite) => {
+      sprite.images.forEach((orderMap) => {
+        orderMap.forEach((imageState) => {
+          if (imageState.imageId === imageId) {
+            removeImageBoundsFromHitTestTree(imageState);
+          }
+        });
+      });
+    });
     const glContext = gl;
     if (glContext && image.texture) {
       glContext.deleteTexture(image.texture);
@@ -24695,13 +26106,16 @@ const createSpriteLayer = (options) => {
       }
     });
     images.clear();
+    hitTestTree.clear();
+    hitTestTreeItems = /* @__PURE__ */ new WeakMap();
+    hitTestEntryByImage = /* @__PURE__ */ new WeakMap();
     clearTextureQueue();
     ensureRenderTargetEntries();
     scheduleRender();
   };
   const getAllImageIds = () => Array.from(images.keys());
   const addSpriteInternal = (spriteId, init) => {
-    var _a2, _b, _c, _d;
+    var _a2, _b, _c, _d, _e;
     if (sprites.get(spriteId)) {
       return false;
     }
@@ -24762,23 +26176,33 @@ const createSpriteLayer = (options) => {
       }
     }
     const currentLocation = cloneSpriteLocation(init.location);
+    const initialAltitude = (_c = currentLocation.z) != null ? _c : 0;
+    const initialMercator = maplibreGlExports.MercatorCoordinate.fromLngLat(
+      { lng: currentLocation.lng, lat: currentLocation.lat },
+      initialAltitude
+    );
     const spriteState = {
       spriteId,
       // Sprites default to enabled unless explicitly disabled in the init payload.
-      isEnabled: (_c = init.isEnabled) != null ? _c : true,
+      isEnabled: (_d = init.isEnabled) != null ? _d : true,
       currentLocation,
       fromLocation: void 0,
       toLocation: void 0,
       images: images2,
       // Tags default to null to simplify downstream comparisons.
-      tag: (_d = init.tag) != null ? _d : null,
+      tag: (_e = init.tag) != null ? _e : null,
       interpolationState: null,
       pendingInterpolationOptions: null,
       lastCommandLocation: cloneSpriteLocation(currentLocation),
       lastAutoRotationLocation: cloneSpriteLocation(currentLocation),
-      lastAutoRotationAngleDeg: 0
+      lastAutoRotationAngleDeg: 0,
+      cachedMercator: initialMercator,
+      cachedMercatorLng: currentLocation.lng,
+      cachedMercatorLat: currentLocation.lat,
+      cachedMercatorZ: initialAltitude
     };
     sprites.set(spriteId, spriteState);
+    refreshSpriteHitTestBounds(spriteState);
     return true;
   };
   const resolveSpriteInitCollection = (collection) => {
@@ -24813,7 +26237,19 @@ const createSpriteLayer = (options) => {
     }
     return addedCount;
   };
-  const removeSpriteInternal = (spriteId) => sprites.delete(spriteId);
+  const removeSpriteInternal = (spriteId) => {
+    const sprite = sprites.get(spriteId);
+    if (!sprite) {
+      return false;
+    }
+    sprite.images.forEach((orderMap) => {
+      orderMap.forEach((image) => {
+        removeImageBoundsFromHitTestTree(image);
+      });
+    });
+    sprites.delete(spriteId);
+    return true;
+  };
   const removeSprite = (spriteId) => {
     const removed = removeSpriteInternal(spriteId);
     if (!removed) {
@@ -24841,6 +26277,9 @@ const createSpriteLayer = (options) => {
     if (removedCount === 0) {
       return 0;
     }
+    hitTestTree.clear();
+    hitTestTreeItems = /* @__PURE__ */ new WeakMap();
+    hitTestEntryByImage = /* @__PURE__ */ new WeakMap();
     sprites.clear();
     ensureRenderTargetEntries();
     scheduleRender();
@@ -24857,6 +26296,9 @@ const createSpriteLayer = (options) => {
     let removedCount = 0;
     sprite.images.forEach((orderMap) => {
       removedCount += orderMap.size;
+      orderMap.forEach((image) => {
+        removeImageBoundsFromHitTestTree(image);
+      });
     });
     sprite.images.clear();
     ensureRenderTargetEntries();
@@ -24907,6 +26349,7 @@ const createSpriteLayer = (options) => {
     }
     syncImageRotationChannel(state);
     setImageState(sprite, state);
+    registerImageBoundsInHitTestTree(sprite, state);
     resultOut.isUpdated = true;
     return true;
   };
@@ -25019,6 +26462,7 @@ const createSpriteLayer = (options) => {
         hasRotationOverride ? rotationOverride != null ? rotationOverride : null : void 0
       );
     }
+    registerImageBoundsInHitTestTree(sprite, state);
     resultOut.isUpdated = true;
     return true;
   };
@@ -25037,6 +26481,10 @@ const createSpriteLayer = (options) => {
     return true;
   };
   const removeSpriteImageInternal = (sprite, subLayer, order, resultOut) => {
+    const state = getImageState(sprite, subLayer, order);
+    if (state) {
+      removeImageBoundsFromHitTestTree(state);
+    }
     const deleted = deleteImageState(sprite, subLayer, order);
     if (deleted) {
       resultOut.isUpdated = true;
@@ -25066,11 +26514,13 @@ const createSpriteLayer = (options) => {
     }
     let updated = false;
     let isRequiredRender = false;
+    let needsHitTestRefresh = false;
     if (update.isEnabled !== void 0) {
       if (sprite.isEnabled !== update.isEnabled) {
         sprite.isEnabled = update.isEnabled;
         updated = true;
         isRequiredRender = true;
+        needsHitTestRefresh = true;
       }
     }
     let interpolationOptionsForLocation = void 0;
@@ -25147,6 +26597,7 @@ const createSpriteLayer = (options) => {
       }
       sprite.pendingInterpolationOptions = null;
       applyAutoRotation(sprite, newCommandLocation);
+      needsHitTestRefresh = true;
     }
     if (update.tag !== void 0) {
       const nextTag = (_a2 = update.tag) != null ? _a2 : null;
@@ -25155,6 +26606,9 @@ const createSpriteLayer = (options) => {
         updated = true;
       }
     }
+    if (needsHitTestRefresh) {
+      refreshSpriteHitTestBounds(sprite);
+    }
     if (isRequiredRender) {
       return "isRequiredRender";
     }
@@ -25389,6 +26843,21 @@ const createSpriteLayer = (options) => {
     updateSprite,
     mutateSprites,
     updateForEach,
+    setHitTestEnabled: (enabled) => {
+      if (isHitTestEnabled === enabled) {
+        return;
+      }
+      isHitTestEnabled = enabled;
+      hitTestTree.clear();
+      hitTestTreeItems = /* @__PURE__ */ new WeakMap();
+      hitTestEntryByImage = /* @__PURE__ */ new WeakMap();
+      if (!enabled) {
+        return;
+      }
+      sprites.forEach((sprite) => {
+        refreshSpriteHitTestBounds(sprite);
+      });
+    },
     on: addEventListener2,
     off: removeEventListener2
   };