maplibre-gl-layers 0.6.0 → 0.11.0

package/dist/index.cjs

@@ -1,12 +1,15 @@
 "use strict";
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 /*!
  * name: maplibre-gl-layers
- * version: 0.6.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: 481f544de02fd3e71a2ba6c28bbb7eeb98b49eff
+ * git.commit.hash: 371efb126f281333d59ec75cfe788d45f3b1482e
  */
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const UNLIMITED_SPRITE_SCALING_OPTIONS = {
@@ -39,6 +42,270 @@ const BETTER_TEXTURE_FILTERING_OPTIONS = {
   generateMipmaps: true,
   maxAnisotropy: 8
 };
+class SvgSizeResolutionError extends Error {
+  constructor(message, code) {
+    super(message);
+    __publicField(this, "code");
+    this.name = "SvgSizeResolutionError";
+    this.code = code;
+  }
+}
+const parseNumericLength = (value) => {
+  if (!value) {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    return void 0;
+  }
+  const parsed = Number.parseFloat(trimmed);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return void 0;
+  }
+  return parsed;
+};
+const extractStyleLength = (styleValue, property) => {
+  if (!styleValue) {
+    return void 0;
+  }
+  const declarations = styleValue.split(";").map((decl) => decl.trim()).filter((decl) => decl.length > 0);
+  for (const declaration of declarations) {
+    const [prop, rawValue] = declaration.split(":");
+    if (!prop || !rawValue) {
+      continue;
+    }
+    if (prop.trim().toLowerCase() === property) {
+      return parseNumericLength(rawValue);
+    }
+  }
+  return void 0;
+};
+const parseSvgSize = (svgText) => {
+  try {
+    const doc = new DOMParser().parseFromString(svgText, "image/svg+xml");
+    const svg = doc.documentElement;
+    if (!svg || svg.tagName.toLowerCase() !== "svg") {
+      return { hasViewBox: false };
+    }
+    const attrWidth = parseNumericLength(svg.getAttribute("width"));
+    const attrHeight = parseNumericLength(svg.getAttribute("height"));
+    const styleWidth = extractStyleLength(svg.getAttribute("style"), "width");
+    const styleHeight = extractStyleLength(svg.getAttribute("style"), "height");
+    const width = attrWidth != null ? attrWidth : styleWidth;
+    const height = attrHeight != null ? attrHeight : styleHeight;
+    let viewBoxWidth;
+    let viewBoxHeight;
+    let hasViewBox = false;
+    const viewBox = svg.getAttribute("viewBox");
+    if (viewBox) {
+      const parts = viewBox.split(/[\s,]+/).map((part) => Number.parseFloat(part)).filter((part) => Number.isFinite(part));
+      if (parts.length === 4) {
+        viewBoxWidth = parts[2];
+        viewBoxHeight = parts[3];
+        if (viewBoxWidth > 0 && viewBoxHeight > 0) {
+          hasViewBox = true;
+        } else {
+          viewBoxWidth = void 0;
+          viewBoxHeight = void 0;
+        }
+      }
+    }
+    return {
+      width: width !== void 0 && width > 0 ? width : void 0,
+      height: height !== void 0 && height > 0 ? height : void 0,
+      viewBoxWidth,
+      viewBoxHeight,
+      hasViewBox
+    };
+  } catch (e) {
+    return { hasViewBox: false };
+  }
+};
+const determineSvgRasterDimensions = (parsed, options) => {
+  var _a, _b;
+  const overrideWidth = options == null ? void 0 : options.width;
+  const overrideHeight = options == null ? void 0 : options.height;
+  if (overrideWidth !== void 0 && overrideHeight !== void 0 && overrideWidth > 0 && overrideHeight > 0) {
+    return {
+      width: Math.max(1, Math.round(overrideWidth)),
+      height: Math.max(1, Math.round(overrideHeight))
+    };
+  }
+  const intrinsicWidth = parsed == null ? void 0 : parsed.width;
+  const intrinsicHeight = parsed == null ? void 0 : parsed.height;
+  const hasValidViewBox = Boolean(
+    (parsed == null ? void 0 : parsed.hasViewBox) && parsed.viewBoxWidth !== void 0 && parsed.viewBoxHeight !== void 0 && parsed.viewBoxWidth > 0 && parsed.viewBoxHeight > 0
+  );
+  const viewBoxAspect = hasValidViewBox ? parsed.viewBoxWidth / parsed.viewBoxHeight : void 0;
+  let baseWidth;
+  let baseHeight;
+  let aspect = intrinsicWidth !== void 0 && intrinsicHeight !== void 0 && intrinsicHeight > 0 ? intrinsicWidth / intrinsicHeight : viewBoxAspect;
+  if (intrinsicWidth !== void 0 && intrinsicWidth > 0 && intrinsicHeight !== void 0 && intrinsicHeight > 0) {
+    baseWidth = intrinsicWidth;
+    baseHeight = intrinsicHeight;
+  } else if (intrinsicWidth !== void 0 && intrinsicWidth > 0 && aspect !== void 0) {
+    baseWidth = intrinsicWidth;
+    baseHeight = intrinsicWidth / aspect;
+  } else if (intrinsicHeight !== void 0 && intrinsicHeight > 0 && aspect !== void 0) {
+    baseHeight = intrinsicHeight;
+    baseWidth = intrinsicHeight * aspect;
+  } else if (hasValidViewBox && ((_a = options == null ? void 0 : options.svg) == null ? void 0 : _a.useViewBoxDimensions)) {
+    baseWidth = parsed.viewBoxWidth;
+    baseHeight = parsed.viewBoxHeight;
+    aspect = baseWidth / baseHeight;
+  }
+  if ((baseWidth === void 0 || baseHeight === void 0) && hasValidViewBox && !((_b = options == null ? void 0 : options.svg) == null ? void 0 : _b.useViewBoxDimensions)) {
+    throw new SvgSizeResolutionError(
+      "SVG width/height attributes are missing and useViewBoxDimensions option is disabled.",
+      "viewbox-disabled"
+    );
+  }
+  if (baseWidth === void 0 || baseHeight === void 0) {
+    throw new SvgSizeResolutionError(
+      "SVG image lacks sufficient sizing information.",
+      "size-missing"
+    );
+  }
+  aspect = aspect != null ? aspect : baseWidth / baseHeight;
+  let finalWidth = baseWidth;
+  let finalHeight = baseHeight;
+  if (overrideWidth !== void 0 && overrideWidth > 0) {
+    finalWidth = overrideWidth;
+    if (overrideHeight === void 0) {
+      if (aspect === void 0) {
+        throw new SvgSizeResolutionError(
+          "Unable to infer SVG height from width; aspect ratio is undefined.",
+          "invalid-dimensions"
+        );
+      }
+      finalHeight = finalWidth / aspect;
+    }
+  }
+  if (overrideHeight !== void 0 && overrideHeight > 0) {
+    finalHeight = overrideHeight;
+    if (overrideWidth === void 0) {
+      if (aspect === void 0) {
+        throw new SvgSizeResolutionError(
+          "Unable to infer SVG width from height; aspect ratio is undefined.",
+          "invalid-dimensions"
+        );
+      }
+      finalWidth = finalHeight * aspect;
+    }
+  }
+  if (!Number.isFinite(finalWidth) || !Number.isFinite(finalHeight) || finalWidth <= 0 || finalHeight <= 0) {
+    throw new SvgSizeResolutionError(
+      "Resolved SVG dimensions are invalid.",
+      "invalid-dimensions"
+    );
+  }
+  return {
+    width: Math.max(1, Math.round(finalWidth)),
+    height: Math.max(1, Math.round(finalHeight))
+  };
+};
+const isSvgMimeType = (mimeType) => {
+  if (!mimeType) {
+    return false;
+  }
+  return mimeType.toLowerCase().includes("image/svg");
+};
+const rasterizeSvgWithCanvas = async (blob, width, height, options) => {
+  if (typeof document === "undefined") {
+    throw new Error(
+      "SVG rasterization fallback requires a browser environment"
+    );
+  }
+  const blobUrl = URL.createObjectURL(blob);
+  try {
+    const image = await new Promise((resolve, reject) => {
+      const element = new Image();
+      element.onload = () => resolve(element);
+      element.onerror = () => reject(new Error("Failed to load SVG for rasterization"));
+      element.src = blobUrl;
+    });
+    const canvas = document.createElement("canvas");
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) {
+      throw new Error("Failed to acquire 2D context for SVG rasterization");
+    }
+    ctx.clearRect(0, 0, width, height);
+    ctx.imageSmoothingEnabled = true;
+    if ((options == null ? void 0 : options.resizeQuality) === "pixelated") {
+      ctx.imageSmoothingEnabled = false;
+    } else if (options == null ? void 0 : options.resizeQuality) {
+      ctx.imageSmoothingQuality = options.resizeQuality;
+    }
+    ctx.drawImage(image, 0, 0, width, height);
+    try {
+      return await createImageBitmap(canvas);
+    } catch (e) {
+      const canvasBlob = await new Promise((resolve, reject) => {
+        canvas.toBlob((result) => {
+          if (result) {
+            resolve(result);
+          } else {
+            reject(
+              new Error("Failed to convert canvas to blob during rasterization")
+            );
+          }
+        });
+      });
+      return await createImageBitmap(canvasBlob);
+    }
+  } finally {
+    URL.revokeObjectURL(blobUrl);
+  }
+};
+const resolveSvgBitmapWithFallback = async (blob, width, height, options) => {
+  const bitmapOptions = {
+    resizeWidth: width,
+    resizeHeight: height
+  };
+  if (options == null ? void 0 : options.resizeQuality) {
+    bitmapOptions.resizeQuality = options.resizeQuality;
+  }
+  try {
+    return await createImageBitmap(blob, bitmapOptions);
+  } catch (error) {
+    return await rasterizeSvgWithCanvas(blob, width, height, options);
+  }
+};
+const internalReadImageBitmap = async (blob, shouldTreatAsSvg, options) => {
+  const svgOptions = options == null ? void 0 : options.svg;
+  if (shouldTreatAsSvg) {
+    let parsed = null;
+    if ((svgOptions == null ? void 0 : svgOptions.inspectSize) !== false) {
+      const text = await blob.text();
+      parsed = parseSvgSize(text);
+    }
+    const { width, height } = determineSvgRasterDimensions(parsed, options);
+    return await resolveSvgBitmapWithFallback(blob, width, height, options);
+  }
+  return await createImageBitmap(blob, {
+    resizeWidth: options == null ? void 0 : options.width,
+    resizeHeight: options == null ? void 0 : options.height,
+    resizeQuality: options == null ? void 0 : options.resizeQuality
+  });
+};
+const readImageBitmap = (blob, options) => {
+  const svgOptions = options == null ? void 0 : options.svg;
+  const shouldTreatAsSvg = (svgOptions == null ? void 0 : svgOptions.assumeSvg) === true;
+  return internalReadImageBitmap(blob, shouldTreatAsSvg, options);
+};
+const loadImageBitmap = async (url, options) => {
+  var _a;
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch image from ${url}`);
+  }
+  const mimeType = response.headers.get("content-type");
+  const blob = await response.blob();
+  const shouldTreatAsSvg = ((_a = options == null ? void 0 : options.svg) == null ? void 0 : _a.assumeSvg) === true || isSvgMimeType(mimeType);
+  return await internalReadImageBitmap(blob, shouldTreatAsSvg, options);
+};
 var maplibreGl$1 = { exports: {} };
 /**
  * MapLibre GL JS
@@ -21113,14 +21380,6 @@ function transformMat4(out, a, m) {
     return a;
   };
 })();
-const loadImageBitmap = async (url) => {
-  const response = await fetch(url);
-  if (!response.ok) {
-    throw new Error(`Failed to fetch image from ${url}`);
-  }
-  const blob = await response.blob();
-  return await createImageBitmap(blob);
-};
 const cloneSpriteLocation = (location2) => {
   if (location2.z === void 0) {
     return { lng: location2.lng, lat: location2.lat };
@@ -21177,7 +21436,7 @@ const computeFeedforwardTarget = (previous, next) => {
   }
   return target;
 };
-const normaliseOptions$1 = (options) => {
+const normalizeOptions$2 = (options) => {
   var _a;
   return {
     durationMs: Math.max(0, options.durationMs),
@@ -21187,7 +21446,7 @@ const normaliseOptions$1 = (options) => {
 };
 const createInterpolationState = (params) => {
   const { currentLocation, lastCommandLocation, nextCommandLocation } = params;
-  const options = normaliseOptions$1(params.options);
+  const options = normalizeOptions$2(params.options);
   const from = cloneSpriteLocation(currentLocation);
   const easing = resolveEasing(options.easing);
   let to;
@@ -21232,8 +21491,8 @@ const evaluateInterpolation = (params) => {
   };
 };
 const NUMERIC_EPSILON = 1e-6;
-const normaliseDuration = (durationMs) => Number.isFinite(durationMs) && durationMs > 0 ? durationMs : 0;
-const normaliseDelta = (delta) => {
+const normalizeDuration$1 = (durationMs) => Number.isFinite(durationMs) && durationMs > 0 ? durationMs : 0;
+const normalizeDelta = (delta) => {
   if (!Number.isFinite(delta)) {
     return 0;
   }
@@ -21245,16 +21504,24 @@ const normaliseDelta = (delta) => {
   }
   return adjusted;
 };
-const normaliseOptions = (options) => {
+const normalizeOptions$1 = (options) => {
+  var _a;
   return {
-    durationMs: normaliseDuration(options.durationMs),
-    easing: resolveEasing(options.easing)
+    durationMs: normalizeDuration$1(options.durationMs),
+    easing: resolveEasing(options.easing),
+    mode: (_a = options.mode) != null ? _a : "feedback"
   };
 };
-const createNumericInterpolationState = (params) => {
+const createDegreeInterpolationState = (params) => {
   const { currentValue, targetValue } = params;
-  const options = normaliseOptions(params.options);
-  const delta = normaliseDelta(targetValue - currentValue);
+  const options = normalizeOptions$1(params.options);
+  let effectiveTarget = targetValue;
+  const previousCommand = params.previousCommandValue;
+  if (options.mode === "feedforward" && previousCommand !== void 0 && Number.isFinite(previousCommand)) {
+    const commandDelta = normalizeDelta(targetValue - previousCommand);
+    effectiveTarget = targetValue + commandDelta;
+  }
+  const delta = normalizeDelta(effectiveTarget - currentValue);
   const pathTarget = currentValue + delta;
   const requiresInterpolation = options.durationMs > 0 && Math.abs(delta) > NUMERIC_EPSILON;
   const state = {
@@ -21262,7 +21529,7 @@ const createNumericInterpolationState = (params) => {
     easing: options.easing,
     from: currentValue,
     to: pathTarget,
-    finalValue: targetValue,
+    finalValue: effectiveTarget,
     startTimestamp: -1
   };
   return {
@@ -21270,7 +21537,7 @@ const createNumericInterpolationState = (params) => {
     requiresInterpolation
   };
 };
-const clamp01 = (value) => {
+const clamp01$1 = (value) => {
   if (!Number.isFinite(value)) {
     return 1;
   }
@@ -21282,7 +21549,7 @@ const clamp01 = (value) => {
   }
   return value;
 };
-const evaluateNumericInterpolation = (params) => {
+const evaluateDegreeInterpolation = (params) => {
   const { state } = params;
   const timestamp = Number.isFinite(params.timestamp) ? params.timestamp : Date.now();
   const duration = Math.max(0, state.durationMs);
@@ -21296,7 +21563,7 @@ const evaluateNumericInterpolation = (params) => {
   }
   const elapsed = timestamp - effectiveStart;
   const rawProgress = duration <= 0 ? 1 : elapsed / duration;
-  const eased = clamp01(state.easing(rawProgress));
+  const eased = clamp01$1(state.easing(rawProgress));
   const interpolated = state.from + (state.to - state.from) * eased;
   const completed = rawProgress >= 1;
   return {
@@ -21305,7 +21572,7 @@ const evaluateNumericInterpolation = (params) => {
     effectiveStartTimestamp: effectiveStart
   };
 };
-const normaliseAngleDeg = (angle) => {
+const normalizeAngleDeg = (angle) => {
   if (!Number.isFinite(angle)) {
     return 0;
   }
@@ -21315,17 +21582,19 @@ const normaliseAngleDeg = (angle) => {
 };
 const resolveRotationTarget = (params) => {
   const options = params.options;
-  const targetAngle = normaliseAngleDeg(params.targetAngleDeg);
-  const currentAngle = normaliseAngleDeg(params.currentAngleDeg);
+  const targetAngle = normalizeAngleDeg(params.targetAngleDeg);
+  const currentAngle = normalizeAngleDeg(params.currentAngleDeg);
+  const previousCommandAngleDeg = params.previousCommandAngleDeg !== void 0 ? normalizeAngleDeg(params.previousCommandAngleDeg) : void 0;
   if (!options || options.durationMs <= 0) {
     return {
       nextAngleDeg: targetAngle,
       interpolationState: null
     };
   }
-  const { state, requiresInterpolation } = createNumericInterpolationState({
+  const { state, requiresInterpolation } = createDegreeInterpolationState({
     currentValue: currentAngle,
     targetValue: targetAngle,
+    previousCommandValue: previousCommandAngleDeg,
     options
   });
   if (!requiresInterpolation) {
@@ -21667,13 +21936,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) {
@@ -21818,41 +22080,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;
@@ -21962,7 +22238,7 @@ const calculateSurfaceCenterPosition = (params) => {
     anchorlessLngLat
   };
 };
-const SURFACE_BASE_CORNERS = [
+const SURFACE_BASE_CORNERS$1 = [
   [-1, 1],
   [1, 1],
   [-1, -1],
@@ -21978,7 +22254,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
     }));
@@ -21991,7 +22267,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;
@@ -22005,115 +22281,602 @@ const calculateSurfaceCornerDisplacements = (params) => {
   }
   return corners;
 };
-const DEFAULT_ANCHOR = { x: 0, y: 0 };
-const DEFAULT_AUTO_ROTATION_MIN_DISTANCE_METERS = 20;
-const DEFAULT_IMAGE_OFFSET = {
-  offsetMeters: 0,
-  offsetDeg: 0
-};
-const MIN_CLIP_W = 1e-6;
-const MIN_CLIP_Z_EPSILON = 1e-7;
-const EPS_NDC = 1e-6;
-const ORDER_MAX = 16;
-const ORDER_BUCKET = 16;
-const MIN_FILTER_VALUES = [
-  "nearest",
-  "linear",
-  "nearest-mipmap-nearest",
-  "nearest-mipmap-linear",
-  "linear-mipmap-nearest",
-  "linear-mipmap-linear"
-];
-const MAG_FILTER_VALUES = [
-  "nearest",
-  "linear"
-];
-const MIPMAP_MIN_FILTERS = /* @__PURE__ */ new Set([
-  "nearest-mipmap-nearest",
-  "nearest-mipmap-linear",
-  "linear-mipmap-nearest",
-  "linear-mipmap-linear"
-]);
-const filterRequiresMipmaps = (filter) => MIPMAP_MIN_FILTERS.has(filter);
-const resolveTextureFilteringOptions = (options) => {
-  var _a, _b;
-  const minCandidate = options == null ? void 0 : options.minFilter;
-  const minFilter = MIN_FILTER_VALUES.includes(
-    minCandidate
-  ) ? minCandidate : DEFAULT_TEXTURE_FILTERING_OPTIONS.minFilter;
-  const magCandidate = options == null ? void 0 : options.magFilter;
-  const magFilter = MAG_FILTER_VALUES.includes(
-    magCandidate
-  ) ? magCandidate : DEFAULT_TEXTURE_FILTERING_OPTIONS.magFilter;
-  let generateMipmaps = (_a = options == null ? void 0 : options.generateMipmaps) != null ? _a : DEFAULT_TEXTURE_FILTERING_OPTIONS.generateMipmaps;
-  if (filterRequiresMipmaps(minFilter)) {
-    generateMipmaps = true;
-  }
-  let maxAnisotropy = (_b = options == null ? void 0 : options.maxAnisotropy) != null ? _b : DEFAULT_TEXTURE_FILTERING_OPTIONS.maxAnisotropy;
-  if (!Number.isFinite(maxAnisotropy) || maxAnisotropy < 1) {
-    maxAnisotropy = 1;
-  }
+const DISTANCE_EPSILON = 1e-6;
+const normalizeDuration = (durationMs) => Number.isFinite(durationMs) && durationMs > 0 ? durationMs : 0;
+const normalizeOptions = (options) => {
+  var _a;
   return {
-    minFilter,
-    magFilter,
-    generateMipmaps,
-    maxAnisotropy
+    durationMs: normalizeDuration(options.durationMs),
+    easing: resolveEasing(options.easing),
+    mode: (_a = options.mode) != null ? _a : "feedback"
   };
 };
-const ANISOTROPY_EXTENSION_NAMES = [
-  "EXT_texture_filter_anisotropic",
-  "WEBKIT_EXT_texture_filter_anisotropic",
-  "MOZ_EXT_texture_filter_anisotropic"
-];
-const resolveAnisotropyExtension = (glContext) => {
-  for (const name of ANISOTROPY_EXTENSION_NAMES) {
-    const extension = glContext.getExtension(name);
-    if (extension) {
-      return extension;
-    }
+const createDistanceInterpolationState = (params) => {
+  const { currentValue, targetValue } = params;
+  const options = normalizeOptions(params.options);
+  let effectiveTarget = targetValue;
+  const previousCommand = params.previousCommandValue;
+  if (options.mode === "feedforward" && previousCommand !== void 0 && Number.isFinite(previousCommand)) {
+    const commandDelta = targetValue - previousCommand;
+    effectiveTarget = targetValue + commandDelta;
   }
-  return null;
+  const delta = effectiveTarget - currentValue;
+  const requiresInterpolation = options.durationMs > 0 && Math.abs(delta) > DISTANCE_EPSILON;
+  const state = {
+    durationMs: options.durationMs,
+    easing: options.easing,
+    from: currentValue,
+    to: currentValue + delta,
+    finalValue: effectiveTarget,
+    startTimestamp: -1
+  };
+  return {
+    state,
+    requiresInterpolation
+  };
 };
-const isPowerOfTwo = (value) => value > 0 && (value & value - 1) === 0;
-const resolveGlMinFilter = (glContext, filter) => {
-  switch (filter) {
-    case "nearest":
-      return glContext.NEAREST;
-    case "nearest-mipmap-nearest":
-      return glContext.NEAREST_MIPMAP_NEAREST;
-    case "nearest-mipmap-linear":
-      return glContext.NEAREST_MIPMAP_LINEAR;
-    case "linear-mipmap-nearest":
-      return glContext.LINEAR_MIPMAP_NEAREST;
-    case "linear-mipmap-linear":
-      return glContext.LINEAR_MIPMAP_LINEAR;
-    case "linear":
-    default:
-      return glContext.LINEAR;
+const clamp01 = (value) => {
+  if (!Number.isFinite(value)) {
+    return 1;
   }
-};
-const resolveGlMagFilter = (glContext, filter) => {
-  switch (filter) {
-    case "nearest":
-      return glContext.NEAREST;
-    case "linear":
-    default:
-      return glContext.LINEAR;
+  if (value <= 0) {
+    return 0;
   }
-};
-const calculatePerspectiveRatio = (mapInstance, location2) => {
-  var _a, _b, _c;
-  const transform = mapInstance.transform;
-  if (!transform) {
+  if (value >= 1) {
     return 1;
   }
-  const mercatorMatrix = (_a = transform.mercatorMatrix) != null ? _a : transform._mercatorMatrix;
+  return value;
+};
+const evaluateDistanceInterpolation = (params) => {
+  const { state } = params;
+  const timestamp = Number.isFinite(params.timestamp) ? params.timestamp : Date.now();
+  const duration = Math.max(0, state.durationMs);
+  const effectiveStart = state.startTimestamp >= 0 ? state.startTimestamp : timestamp;
+  if (duration === 0 || Math.abs(state.to - state.from) <= DISTANCE_EPSILON) {
+    return {
+      value: state.finalValue,
+      completed: true,
+      effectiveStartTimestamp: effectiveStart
+    };
+  }
+  const elapsed = timestamp - effectiveStart;
+  const rawProgress = duration <= 0 ? 1 : elapsed / duration;
+  const eased = clamp01(state.easing(rawProgress));
+  const interpolated = state.from + (state.to - state.from) * eased;
+  const completed = rawProgress >= 1;
+  return {
+    value: completed ? state.finalValue : interpolated,
+    completed,
+    effectiveStartTimestamp: effectiveStart
+  };
+};
+const stepDegreeInterpolationState = (interpolationState, timestamp, applyValue, options) => {
+  var _a, _b;
+  if (!interpolationState) {
+    return { state: null, active: false };
+  }
+  const evaluation = evaluateDegreeInterpolation({
+    state: interpolationState,
+    timestamp
+  });
+  if (interpolationState.startTimestamp < 0) {
+    interpolationState.startTimestamp = evaluation.effectiveStartTimestamp;
+  }
+  const normalizeValue = (_a = options == null ? void 0 : options.normalize) != null ? _a : ((value) => value);
+  const applyFinalValue = (_b = options == null ? void 0 : options.applyFinalValue) != null ? _b : applyValue;
+  const interpolatedValue = normalizeValue(evaluation.value);
+  applyValue(interpolatedValue);
+  if (evaluation.completed) {
+    const finalValue = normalizeValue(interpolationState.finalValue);
+    applyFinalValue(finalValue);
+    return { state: null, active: false };
+  }
+  return { state: interpolationState, active: true };
+};
+const updateImageDisplayedRotation = (image, optionsOverride) => {
+  const targetAngle = normalizeAngleDeg(
+    image.resolvedBaseRotateDeg + image.rotateDeg
+  );
+  const currentAngle = Number.isFinite(image.displayedRotateDeg) ? image.displayedRotateDeg : targetAngle;
+  const previousCommandAngle = image.lastCommandRotateDeg;
+  const options = optionsOverride === void 0 ? image.rotationInterpolationOptions : optionsOverride;
+  const { nextAngleDeg, interpolationState } = resolveRotationTarget({
+    currentAngleDeg: currentAngle,
+    targetAngleDeg: targetAngle,
+    previousCommandAngleDeg: previousCommandAngle,
+    options: options != null ? options : void 0
+  });
+  image.displayedRotateDeg = nextAngleDeg;
+  image.rotationInterpolationState = interpolationState;
+  if (!interpolationState) {
+    image.displayedRotateDeg = targetAngle;
+  }
+  image.lastCommandRotateDeg = targetAngle;
+};
+const syncImageRotationChannel = (image, optionsOverride) => {
+  updateImageDisplayedRotation(image, optionsOverride);
+};
+const stepRotationInterpolation = (image, timestamp) => {
+  const { state, active } = stepDegreeInterpolationState(
+    image.rotationInterpolationState,
+    timestamp,
+    (value) => {
+      image.displayedRotateDeg = value;
+    },
+    {
+      normalize: normalizeAngleDeg
+    }
+  );
+  image.rotationInterpolationState = state;
+  return active;
+};
+const stepOffsetDegInterpolation = (image, timestamp) => {
+  const { state, active } = stepDegreeInterpolationState(
+    image.offsetDegInterpolationState,
+    timestamp,
+    (value) => {
+      image.offset.offsetDeg = value;
+    }
+  );
+  image.offsetDegInterpolationState = state;
+  return active;
+};
+const clearOffsetDegInterpolation = (image) => {
+  image.offsetDegInterpolationState = null;
+};
+const stepDistanceInterpolationState = (interpolationState, timestamp, applyValue) => {
+  if (!interpolationState) {
+    return { state: null, active: false };
+  }
+  const evaluation = evaluateDistanceInterpolation({
+    state: interpolationState,
+    timestamp
+  });
+  if (interpolationState.startTimestamp < 0) {
+    interpolationState.startTimestamp = evaluation.effectiveStartTimestamp;
+  }
+  applyValue(evaluation.value);
+  if (evaluation.completed) {
+    applyValue(interpolationState.finalValue);
+    return { state: null, active: false };
+  }
+  return { state: interpolationState, active: true };
+};
+const clearOffsetMetersInterpolation = (image) => {
+  image.offsetMetersInterpolationState = null;
+};
+const applyOffsetDegUpdate = (image, nextOffset, interpolationOptions) => {
+  const options = interpolationOptions;
+  if (!options || options.durationMs <= 0) {
+    image.offset.offsetDeg = nextOffset.offsetDeg;
+    image.offsetDegInterpolationState = null;
+    image.lastCommandOffsetDeg = nextOffset.offsetDeg;
+    return;
+  }
+  const { state, requiresInterpolation } = createDegreeInterpolationState({
+    currentValue: image.offset.offsetDeg,
+    targetValue: nextOffset.offsetDeg,
+    previousCommandValue: image.lastCommandOffsetDeg,
+    options
+  });
+  image.lastCommandOffsetDeg = nextOffset.offsetDeg;
+  if (requiresInterpolation) {
+    image.offsetDegInterpolationState = state;
+  } else {
+    image.offset.offsetDeg = nextOffset.offsetDeg;
+    image.offsetDegInterpolationState = null;
+  }
+};
+const applyOffsetMetersUpdate = (image, nextOffset, interpolationOptions) => {
+  const options = interpolationOptions;
+  if (!options || options.durationMs <= 0) {
+    image.offset.offsetMeters = nextOffset.offsetMeters;
+    image.offsetMetersInterpolationState = null;
+    image.lastCommandOffsetMeters = nextOffset.offsetMeters;
+    return;
+  }
+  const { state, requiresInterpolation } = createDistanceInterpolationState({
+    currentValue: image.offset.offsetMeters,
+    targetValue: nextOffset.offsetMeters,
+    previousCommandValue: image.lastCommandOffsetMeters,
+    options
+  });
+  image.lastCommandOffsetMeters = nextOffset.offsetMeters;
+  if (requiresInterpolation) {
+    image.offsetMetersInterpolationState = state;
+  } else {
+    image.offset.offsetMeters = nextOffset.offsetMeters;
+    image.offsetMetersInterpolationState = null;
+  }
+};
+const stepOffsetMetersInterpolation = (image, timestamp) => {
+  const { state, active } = stepDistanceInterpolationState(
+    image.offsetMetersInterpolationState,
+    timestamp,
+    (value) => {
+      image.offset.offsetMeters = value;
+    }
+  );
+  image.offsetMetersInterpolationState = state;
+  return active;
+};
+const IMAGE_INTERPOLATION_STEPPERS = [
+  stepRotationInterpolation,
+  stepOffsetDegInterpolation,
+  stepOffsetMetersInterpolation
+];
+const stepSpriteImageInterpolations = (image, timestamp) => {
+  let active = false;
+  for (const stepper of IMAGE_INTERPOLATION_STEPPERS) {
+    if (stepper(image, timestamp)) {
+      active = true;
+    }
+  }
+  return active;
+};
+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;
+const ORDER_MAX = 16;
+const ORDER_BUCKET = 16;
+const MIN_FILTER_VALUES = [
+  "nearest",
+  "linear",
+  "nearest-mipmap-nearest",
+  "nearest-mipmap-linear",
+  "linear-mipmap-nearest",
+  "linear-mipmap-linear"
+];
+const MAG_FILTER_VALUES = [
+  "nearest",
+  "linear"
+];
+const MIPMAP_MIN_FILTERS = /* @__PURE__ */ new Set([
+  "nearest-mipmap-nearest",
+  "nearest-mipmap-linear",
+  "linear-mipmap-nearest",
+  "linear-mipmap-linear"
+]);
+const filterRequiresMipmaps = (filter) => MIPMAP_MIN_FILTERS.has(filter);
+const resolveTextureFilteringOptions = (options) => {
+  var _a, _b;
+  const minCandidate = options == null ? void 0 : options.minFilter;
+  const minFilter = MIN_FILTER_VALUES.includes(
+    minCandidate
+  ) ? minCandidate : DEFAULT_TEXTURE_FILTERING_OPTIONS.minFilter;
+  const magCandidate = options == null ? void 0 : options.magFilter;
+  const magFilter = MAG_FILTER_VALUES.includes(
+    magCandidate
+  ) ? magCandidate : DEFAULT_TEXTURE_FILTERING_OPTIONS.magFilter;
+  let generateMipmaps = (_a = options == null ? void 0 : options.generateMipmaps) != null ? _a : DEFAULT_TEXTURE_FILTERING_OPTIONS.generateMipmaps;
+  if (filterRequiresMipmaps(minFilter)) {
+    generateMipmaps = true;
+  }
+  let maxAnisotropy = (_b = options == null ? void 0 : options.maxAnisotropy) != null ? _b : DEFAULT_TEXTURE_FILTERING_OPTIONS.maxAnisotropy;
+  if (!Number.isFinite(maxAnisotropy) || maxAnisotropy < 1) {
+    maxAnisotropy = 1;
+  }
+  return {
+    minFilter,
+    magFilter,
+    generateMipmaps,
+    maxAnisotropy
+  };
+};
+const ANISOTROPY_EXTENSION_NAMES = [
+  "EXT_texture_filter_anisotropic",
+  "WEBKIT_EXT_texture_filter_anisotropic",
+  "MOZ_EXT_texture_filter_anisotropic"
+];
+const resolveAnisotropyExtension = (glContext) => {
+  for (const name of ANISOTROPY_EXTENSION_NAMES) {
+    const extension = glContext.getExtension(name);
+    if (extension) {
+      return extension;
+    }
+  }
+  return null;
+};
+const isPowerOfTwo = (value) => value > 0 && (value & value - 1) === 0;
+const resolveGlMinFilter = (glContext, filter) => {
+  switch (filter) {
+    case "nearest":
+      return glContext.NEAREST;
+    case "nearest-mipmap-nearest":
+      return glContext.NEAREST_MIPMAP_NEAREST;
+    case "nearest-mipmap-linear":
+      return glContext.NEAREST_MIPMAP_LINEAR;
+    case "linear-mipmap-nearest":
+      return glContext.LINEAR_MIPMAP_NEAREST;
+    case "linear-mipmap-linear":
+      return glContext.LINEAR_MIPMAP_LINEAR;
+    case "linear":
+    default:
+      return glContext.LINEAR;
+  }
+};
+const resolveGlMagFilter = (glContext, filter) => {
+  switch (filter) {
+    case "nearest":
+      return glContext.NEAREST;
+    case "linear":
+    default:
+      return glContext.LINEAR;
+  }
+};
+const calculatePerspectiveRatio = (mapInstance, location2, cachedMercator) => {
+  var _a, _b, _c;
+  const transform = mapInstance.transform;
+  if (!transform) {
+    return 1;
+  }
+  const mercatorMatrix = (_a = transform.mercatorMatrix) != null ? _a : transform._mercatorMatrix;
   const cameraToCenterDistance = transform.cameraToCenterDistance;
   if (!mercatorMatrix || typeof cameraToCenterDistance !== "number" || !Number.isFinite(cameraToCenterDistance)) {
     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
     );
@@ -22222,14 +22985,14 @@ const applyAutoRotation = (sprite, nextLocation) => {
     return false;
   }
   const resolvedAngleRaw = isFiniteNumber(bearingDeg) ? bearingDeg : sprite.lastAutoRotationAngleDeg;
-  const resolvedAngle = normaliseAngleDeg(resolvedAngleRaw);
+  const resolvedAngle = normalizeAngleDeg(resolvedAngleRaw);
   sprite.images.forEach((orderMap) => {
     orderMap.forEach((image) => {
       if (!image.autoRotation) {
         return;
       }
       image.resolvedBaseRotateDeg = resolvedAngle;
-      updateImageDisplayedRotation(image);
+      syncImageRotationChannel(image);
     });
   });
   sprite.lastAutoRotationLocation = cloneSpriteLocation(nextLocation);
@@ -22246,10 +23009,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 = `
@@ -22268,6 +23080,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);
@@ -22665,23 +23646,6 @@ const cloneOffset = (offset) => {
     offsetDeg: offset.offsetDeg
   };
 };
-const updateImageDisplayedRotation = (image, optionsOverride) => {
-  const targetAngle = normaliseAngleDeg(
-    image.resolvedBaseRotateDeg + image.rotateDeg
-  );
-  const currentAngle = Number.isFinite(image.displayedRotateDeg) ? image.displayedRotateDeg : targetAngle;
-  const options = optionsOverride === void 0 ? image.rotationInterpolationOptions : optionsOverride;
-  const { nextAngleDeg, interpolationState } = resolveRotationTarget({
-    currentAngleDeg: currentAngle,
-    targetAngleDeg: targetAngle,
-    options: options != null ? options : void 0
-  });
-  image.displayedRotateDeg = nextAngleDeg;
-  image.rotationInterpolationState = interpolationState;
-  if (!interpolationState) {
-    image.displayedRotateDeg = targetAngle;
-  }
-};
 const cloneInterpolationOptions = (options) => {
   return {
     mode: options.mode,
@@ -22689,40 +23653,40 @@ const cloneInterpolationOptions = (options) => {
     easing: options.easing
   };
 };
-const cloneNumericInterpolationOptions = (options) => {
-  return {
-    durationMs: options.durationMs,
-    easing: options.easing
-  };
-};
 const createImageStateFromInit = (imageInit, subLayer, order) => {
   var _a, _b, _c, _d, _e, _f, _g, _h, _i;
   const mode = (_a = imageInit.mode) != null ? _a : "surface";
   const autoRotationDefault = mode === "surface";
+  const initialOffset = cloneOffset(imageInit.offset);
+  const initialRotateDeg = normalizeAngleDeg((_b = imageInit.rotateDeg) != null ? _b : 0);
   const state = {
     subLayer,
     order,
     imageId: imageInit.imageId,
     mode,
-    opacity: (_b = imageInit.opacity) != null ? _b : 1,
-    scale: (_c = imageInit.scale) != null ? _c : 1,
+    opacity: (_c = imageInit.opacity) != null ? _c : 1,
+    scale: (_d = imageInit.scale) != null ? _d : 1,
     anchor: cloneAnchor(imageInit.anchor),
-    offset: cloneOffset(imageInit.offset),
-    rotateDeg: (_d = imageInit.rotateDeg) != null ? _d : 0,
-    displayedRotateDeg: normaliseAngleDeg((_e = imageInit.rotateDeg) != null ? _e : 0),
+    offset: initialOffset,
+    rotateDeg: (_e = imageInit.rotateDeg) != null ? _e : 0,
+    displayedRotateDeg: initialRotateDeg,
     autoRotation: (_f = imageInit.autoRotation) != null ? _f : autoRotationDefault,
     autoRotationMinDistanceMeters: (_g = imageInit.autoRotationMinDistanceMeters) != null ? _g : DEFAULT_AUTO_ROTATION_MIN_DISTANCE_METERS,
     resolvedBaseRotateDeg: 0,
     originLocation: cloneOriginLocation(imageInit.originLocation),
     rotationInterpolationState: null,
     rotationInterpolationOptions: null,
-    offsetInterpolationState: null
+    offsetDegInterpolationState: null,
+    offsetMetersInterpolationState: null,
+    lastCommandRotateDeg: initialRotateDeg,
+    lastCommandOffsetDeg: initialOffset.offsetDeg,
+    lastCommandOffsetMeters: initialOffset.offsetMeters
   };
-  const rotateInitOption = (_i = (_h = imageInit.rotationInterpolation) == null ? void 0 : _h.rotateDeg) != null ? _i : null;
+  const rotateInitOption = (_i = (_h = imageInit.interpolation) == null ? void 0 : _h.rotateDeg) != null ? _i : null;
   if (rotateInitOption) {
-    state.rotationInterpolationOptions = cloneNumericInterpolationOptions(rotateInitOption);
+    state.rotationInterpolationOptions = cloneInterpolationOptions(rotateInitOption);
   }
-  updateImageDisplayedRotation(state);
+  syncImageRotationChannel(state);
   return state;
 };
 const createSpriteLayer = (options) => {
@@ -22732,6 +23696,7 @@ const createSpriteLayer = (options) => {
   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;
@@ -22740,8 +23705,27 @@ const createSpriteLayer = (options) => {
   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) => {
@@ -22754,6 +23738,347 @@ const createSpriteLayer = (options) => {
     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 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 refreshSpriteHitTestBounds = (sprite) => {
+    sprite.images.forEach((orderMap) => {
+      orderMap.forEach((image) => {
+        registerImageBoundsInHitTestTree(sprite, image);
+      });
+    });
+  };
   const getImageState = (sprite, subLayer, order) => {
     var _a2;
     return (
@@ -22786,34 +24111,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();
@@ -22872,7 +24201,7 @@ const createSpriteLayer = (options) => {
         baseY = refCenter.y;
       }
     }
-    const totalRotDeg = Number.isFinite(img.displayedRotateDeg) ? img.displayedRotateDeg : normaliseAngleDeg(
+    const totalRotDeg = Number.isFinite(img.displayedRotateDeg) ? img.displayedRotateDeg : normalizeAngleDeg(
       ((_d = img.resolvedBaseRotateDeg) != null ? _d : 0) + ((_e = img.rotateDeg) != null ? _e : 0)
     );
     const imageScaleLocal = (_f = img.scale) != null ? _f : 1;
@@ -22955,6 +24284,7 @@ const createSpriteLayer = (options) => {
   };
   const renderTargetEntries = [];
   const hitTestEntries = [];
+  let hitTestEntryByImage = /* @__PURE__ */ new WeakMap();
   const ensureHitTestCorners = (imageEntry) => {
     if (!imageEntry.hitTestCorners) {
       imageEntry.hitTestCorners = [
@@ -22966,7 +24296,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;
@@ -22979,7 +24312,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,
@@ -22987,16 +24320,82 @@ 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)) {
         return entry;
       }
     }
-    return null;
+    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) => {
@@ -23022,13 +24421,15 @@ const createSpriteLayer = (options) => {
   };
   let canvasElement = null;
   const inputListenerDisposers = [];
-  const hasSpriteClickListeners = () => {
+  const hasSpriteListeners = (type) => {
     var _a2, _b;
     return (
       // Treat missing listener sets as zero, otherwise check the registered count.
-      ((_b = (_a2 = eventListeners.get("spriteclick")) == null ? void 0 : _a2.size) != null ? _b : 0) > 0
+      ((_b = (_a2 = eventListeners.get(type)) == null ? void 0 : _a2.size) != null ? _b : 0) > 0
     );
   };
+  const hasSpriteClickListeners = () => hasSpriteListeners("spriteclick");
+  const hasSpriteHoverListeners = () => hasSpriteListeners("spritehover");
   const resolveScreenPointFromEvent = (nativeEvent) => {
     var _a2, _b, _c, _d;
     if (!canvasElement) {
@@ -23053,20 +24454,31 @@ const createSpriteLayer = (options) => {
     const mouseLike = nativeEvent;
     return toScreenPoint(mouseLike.clientX, mouseLike.clientY);
   };
+  const resolveSpriteEventPayload = (hitEntry) => {
+    var _a2, _b;
+    if (!hitEntry) {
+      return {
+        sprite: void 0,
+        image: void 0
+      };
+    }
+    const spriteState = getSpriteState(hitEntry.sprite.spriteId);
+    const imageState = (_b = (_a2 = spriteState == null ? void 0 : spriteState.images.get(hitEntry.image.subLayer)) == null ? void 0 : _a2.get(hitEntry.image.order)) != null ? _b : void 0;
+    return {
+      sprite: spriteState,
+      image: imageState
+    };
+  };
   const dispatchSpriteClick = (hitEntry, screenPoint, originalEvent) => {
     const listeners = eventListeners.get("spriteclick");
     if (!listeners || listeners.size === 0) {
       return;
     }
-    const spriteState = getSpriteState(hitEntry.sprite.spriteId);
-    if (!spriteState) {
-      return;
-    }
-    const imageState = hitEntry.image;
+    const payload = resolveSpriteEventPayload(hitEntry);
     const clickEvent = {
       type: "spriteclick",
-      sprite: spriteState,
-      image: imageState,
+      sprite: payload.sprite,
+      image: payload.image,
       screenPoint,
       originalEvent
     };
@@ -23074,22 +24486,50 @@ const createSpriteLayer = (options) => {
       listener(clickEvent);
     });
   };
-  const processInteractionEvent = (nativeEvent) => {
+  const dispatchSpriteHover = (hitEntry, screenPoint, originalEvent) => {
+    const listeners = eventListeners.get("spritehover");
+    if (!listeners || listeners.size === 0) {
+      return;
+    }
+    const payload = resolveSpriteEventPayload(hitEntry);
+    const hoverEvent = {
+      type: "spritehover",
+      sprite: payload.sprite,
+      image: payload.image,
+      screenPoint,
+      originalEvent
+    };
+    listeners.forEach((listener) => {
+      listener(hoverEvent);
+    });
+  };
+  const resolveHitTestResult = (nativeEvent) => {
+    const screenPoint = resolveScreenPointFromEvent(nativeEvent);
+    if (!screenPoint) {
+      return null;
+    }
+    const hitEntry = findTopmostHitEntry(screenPoint);
+    return { hitEntry: hitEntry != null ? hitEntry : null, screenPoint };
+  };
+  const processClickEvent = (nativeEvent) => {
     if (!hasSpriteClickListeners()) {
       return;
     }
-    if (hitTestEntries.length === 0) {
+    const hitResult = resolveHitTestResult(nativeEvent);
+    if (!hitResult || !hitResult.hitEntry) {
       return;
     }
-    const screenPoint = resolveScreenPointFromEvent(nativeEvent);
-    if (!screenPoint) {
+    dispatchSpriteClick(hitResult.hitEntry, hitResult.screenPoint, nativeEvent);
+  };
+  const processHoverEvent = (nativeEvent) => {
+    if (!hasSpriteHoverListeners()) {
       return;
     }
-    const hitEntry = findTopmostHitEntry(screenPoint);
-    if (!hitEntry) {
+    const hitResult = resolveHitTestResult(nativeEvent);
+    if (!hitResult) {
       return;
     }
-    dispatchSpriteClick(hitEntry, screenPoint, nativeEvent);
+    dispatchSpriteHover(hitResult.hitEntry, hitResult.screenPoint, nativeEvent);
   };
   const ensureTextures = () => {
     if (!gl) {
@@ -23242,24 +24682,42 @@ const createSpriteLayer = (options) => {
     const supportsPointerEvents = typeof window !== "undefined" && "PointerEvent" in window;
     if (canvasElement) {
       if (supportsPointerEvents) {
-        const pointerListener = (event) => {
+        const pointerUpListener = (event) => {
           if (event.pointerType === "mouse" && event.button !== 0) {
             return;
           }
-          processInteractionEvent(event);
+          processClickEvent(event);
+        };
+        canvasElement.addEventListener("pointerup", pointerUpListener, {
+          passive: true
+        });
+        registerDisposer(() => {
+          canvasElement == null ? void 0 : canvasElement.removeEventListener("pointerup", pointerUpListener);
+        });
+        const pointerMoveListener = (event) => {
+          if (!event.isPrimary) {
+            return;
+          }
+          if (event.pointerType === "touch") {
+            return;
+          }
+          processHoverEvent(event);
         };
-        canvasElement.addEventListener("pointerup", pointerListener, {
+        canvasElement.addEventListener("pointermove", pointerMoveListener, {
           passive: true
         });
         registerDisposer(() => {
-          canvasElement == null ? void 0 : canvasElement.removeEventListener("pointerup", pointerListener);
+          canvasElement == null ? void 0 : canvasElement.removeEventListener(
+            "pointermove",
+            pointerMoveListener
+          );
         });
       } else {
         const clickListener = (event) => {
           if (event.button !== 0) {
             return;
           }
-          processInteractionEvent(event);
+          processClickEvent(event);
         };
         canvasElement.addEventListener("click", clickListener, {
           passive: true
@@ -23268,7 +24726,7 @@ const createSpriteLayer = (options) => {
           canvasElement == null ? void 0 : canvasElement.removeEventListener("click", clickListener);
         });
         const touchListener = (event) => {
-          processInteractionEvent(event);
+          processClickEvent(event);
         };
         canvasElement.addEventListener("touchend", touchListener, {
           passive: true
@@ -23276,6 +24734,15 @@ const createSpriteLayer = (options) => {
         registerDisposer(() => {
           canvasElement == null ? void 0 : canvasElement.removeEventListener("touchend", touchListener);
         });
+        const mouseMoveListener = (event) => {
+          processHoverEvent(event);
+        };
+        canvasElement.addEventListener("mousemove", mouseMoveListener, {
+          passive: true
+        });
+        registerDisposer(() => {
+          canvasElement == null ? void 0 : canvasElement.removeEventListener("mousemove", mouseMoveListener);
+        });
       }
     }
     const buffer = glContext.createBuffer();
@@ -23312,7 +24779,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);
@@ -23335,7 +24854,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 = () => {
@@ -23343,6 +24935,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) => {
@@ -23355,9 +24950,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();
@@ -23365,20 +24966,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" ? (
@@ -23411,41 +25028,8 @@ const createSpriteLayer = (options) => {
       }
       sprite.images.forEach((orderMap) => {
         orderMap.forEach((image) => {
-          const rotationState = image.rotationInterpolationState;
-          if (rotationState) {
-            const evaluation = evaluateNumericInterpolation({
-              state: rotationState,
-              timestamp
-            });
-            if (rotationState.startTimestamp < 0) {
-              rotationState.startTimestamp = evaluation.effectiveStartTimestamp;
-            }
-            image.displayedRotateDeg = normaliseAngleDeg(evaluation.value);
-            if (evaluation.completed) {
-              image.displayedRotateDeg = normaliseAngleDeg(
-                rotationState.finalValue
-              );
-              image.rotationInterpolationState = null;
-            } else {
-              hasActiveInterpolation = true;
-            }
-          }
-          const offsetState = image.offsetInterpolationState;
-          if (offsetState) {
-            const evaluation = evaluateNumericInterpolation({
-              state: offsetState,
-              timestamp
-            });
-            if (offsetState.startTimestamp < 0) {
-              offsetState.startTimestamp = evaluation.effectiveStartTimestamp;
-            }
-            image.offset.offsetDeg = evaluation.value;
-            if (evaluation.completed) {
-              image.offset.offsetDeg = offsetState.finalValue;
-              image.offsetInterpolationState = null;
-            } else {
-              hasActiveInterpolation = true;
-            }
+          if (stepSpriteImageInterpolations(image, timestamp)) {
+            hasActiveInterpolation = true;
           }
         });
       });
@@ -23463,6 +25047,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;
@@ -23497,18 +25092,84 @@ 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;
-      const totalRotateDeg = Number.isFinite(imageEntry.displayedRotateDeg) ? imageEntry.displayedRotateDeg : normaliseAngleDeg(
+      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)
       );
       const projected = mapInstance.project(spriteEntry.currentLocation);
       if (!projected) {
         return;
       }
+      const spriteMercator = resolveSpriteMercator(spriteEntry);
       const metersPerPixelAtLat = calculateMetersPerPixelAtLatitude(
         zoom,
         spriteEntry.currentLocation.lat
@@ -23518,7 +25179,8 @@ const createSpriteLayer = (options) => {
       }
       const perspectiveRatio = calculatePerspectiveRatio(
         mapInstance,
-        spriteEntry.currentLocation
+        spriteEntry.currentLocation,
+        spriteMercator
       );
       const effectivePixelsPerMeter = calculateEffectivePixelsPerMeter(
         metersPerPixelAtLat,
@@ -23528,6 +25190,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,
@@ -23542,7 +25205,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) {
@@ -23559,6 +25222,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([
@@ -23586,7 +25256,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;
@@ -23595,6 +25265,9 @@ const createSpriteLayer = (options) => {
         if (!surfaceCenter.center) {
           return;
         }
+        if (uniformBillboardModeLocation) {
+          glContext.uniform1f(uniformBillboardModeLocation, 0);
+        }
         const offsetMeters = calculateSurfaceOffsetMeters(
           offsetDef,
           imageScale,
@@ -23608,6 +25281,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) {
@@ -23621,46 +25339,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,
@@ -23675,46 +25492,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);
@@ -23744,6 +25610,7 @@ const createSpriteLayer = (options) => {
         if (!projected) {
           continue;
         }
+        const spriteMercator = resolveSpriteMercator(spriteEntry);
         const metersPerPixelAtLat = calculateMetersPerPixelAtLatitude(
           zoom,
           spriteEntry.currentLocation.lat
@@ -23753,7 +25620,8 @@ const createSpriteLayer = (options) => {
         }
         const perspectiveRatio = calculatePerspectiveRatio(
           mapInstance,
-          spriteEntry.currentLocation
+          spriteEntry.currentLocation,
+          spriteMercator
         );
         const effectivePixelsPerMeter = calculateEffectivePixelsPerMeter(
           metersPerPixelAtLat,
@@ -23801,7 +25669,7 @@ const createSpriteLayer = (options) => {
               spriteMaxPixel
             }
           );
-          const totalRotateDeg = Number.isFinite(imageEntry.displayedRotateDeg) ? imageEntry.displayedRotateDeg : normaliseAngleDeg(
+          const totalRotateDeg = Number.isFinite(imageEntry.displayedRotateDeg) ? imageEntry.displayedRotateDeg : normalizeAngleDeg(
             ((_e = imageEntry.resolvedBaseRotateDeg) != null ? _e : 0) + ((_f = imageEntry.rotateDeg) != null ? _f : 0)
           );
           const offsetMeters = calculateSurfaceOffsetMeters(
@@ -23916,13 +25784,83 @@ 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);
     scheduleRender();
   };
-  const registerImage = async (imageId, imageSource) => {
-    const bitmap = typeof imageSource === "string" ? await loadImageBitmap(imageSource) : imageSource;
+  const registerImage = async (imageId, imageSource, options2) => {
+    let bitmap;
+    try {
+      bitmap = typeof imageSource === "string" ? await loadImageBitmap(imageSource, options2) : imageSource;
+    } catch (error) {
+      if (error instanceof SvgSizeResolutionError) {
+        console.warn(
+          `[SpriteLayer] Unable to register image "${imageId}": ${error.message}`,
+          error
+        );
+        return false;
+      }
+      throw error;
+    }
     if (images.has(imageId)) {
       return false;
     }
@@ -24139,6 +26077,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);
@@ -24161,13 +26108,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;
     }
@@ -24228,23 +26178,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) => {
@@ -24279,7 +26239,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) {
@@ -24307,6 +26279,9 @@ const createSpriteLayer = (options) => {
     if (removedCount === 0) {
       return 0;
     }
+    hitTestTree.clear();
+    hitTestTreeItems = /* @__PURE__ */ new WeakMap();
+    hitTestEntryByImage = /* @__PURE__ */ new WeakMap();
     sprites.clear();
     ensureRenderTargetEntries();
     scheduleRender();
@@ -24323,6 +26298,9 @@ const createSpriteLayer = (options) => {
     let removedCount = 0;
     sprite.images.forEach((orderMap) => {
       removedCount += orderMap.size;
+      orderMap.forEach((image) => {
+        removeImageBoundsFromHitTestTree(image);
+      });
     });
     sprite.images.clear();
     ensureRenderTargetEntries();
@@ -24371,8 +26349,9 @@ const createSpriteLayer = (options) => {
     if (state.autoRotation) {
       state.resolvedBaseRotateDeg = sprite.lastAutoRotationAngleDeg;
     }
-    updateImageDisplayedRotation(state);
+    syncImageRotationChannel(state);
     setImageState(sprite, state);
+    registerImageBoundsInHitTestTree(sprite, state);
     resultOut.isUpdated = true;
     return true;
   };
@@ -24412,41 +26391,32 @@ const createSpriteLayer = (options) => {
     if (imageUpdate.anchor !== void 0) {
       state.anchor = cloneAnchor(imageUpdate.anchor);
     }
-    const rotationInterpolation = imageUpdate.rotationInterpolation;
-    const offsetInterpolationOption = rotationInterpolation == null ? void 0 : rotationInterpolation.offsetDeg;
-    const rotateInterpolationOption = rotationInterpolation == null ? void 0 : rotationInterpolation.rotateDeg;
+    const interpolationOptions = imageUpdate.interpolation;
+    const offsetDegInterpolationOption = interpolationOptions == null ? void 0 : interpolationOptions.offsetDeg;
+    const offsetMetersInterpolationOption = interpolationOptions == null ? void 0 : interpolationOptions.offsetMeters;
+    const rotateInterpolationOption = interpolationOptions == null ? void 0 : interpolationOptions.rotateDeg;
     let rotationOverride;
     let hasRotationOverride = false;
     if (imageUpdate.offset !== void 0) {
-      const newOffset = cloneOffset(imageUpdate.offset);
-      if (offsetInterpolationOption && offsetInterpolationOption.durationMs > 0) {
-        const { state: interpolationState, requiresInterpolation } = createNumericInterpolationState({
-          currentValue: state.offset.offsetDeg,
-          targetValue: newOffset.offsetDeg,
-          options: offsetInterpolationOption
-        });
-        if (requiresInterpolation) {
-          state.offset.offsetMeters = newOffset.offsetMeters;
-          state.offsetInterpolationState = interpolationState;
-        } else {
-          state.offset = newOffset;
-          state.offsetInterpolationState = null;
-        }
-      } else {
-        state.offset = newOffset;
-        state.offsetInterpolationState = null;
+      const clonedOffset = cloneOffset(imageUpdate.offset);
+      applyOffsetUpdate(state, clonedOffset, {
+        deg: offsetDegInterpolationOption,
+        meters: offsetMetersInterpolationOption
+      });
+    } else {
+      if (offsetDegInterpolationOption === null) {
+        clearOffsetDegInterpolation(state);
+      }
+      if (offsetMetersInterpolationOption === null) {
+        clearOffsetMetersInterpolation(state);
       }
-    } else if (offsetInterpolationOption === null) {
-      state.offsetInterpolationState = null;
     }
     if (rotateInterpolationOption !== void 0) {
       if (rotateInterpolationOption === null) {
         state.rotationInterpolationOptions = null;
         rotationOverride = null;
       } else {
-        const cloned = cloneNumericInterpolationOptions(
-          rotateInterpolationOption
-        );
+        const cloned = cloneInterpolationOptions(rotateInterpolationOption);
         state.rotationInterpolationOptions = cloned;
         rotationOverride = cloned;
       }
@@ -24488,12 +26458,13 @@ const createSpriteLayer = (options) => {
       }
     }
     if (requireRotationSync) {
-      updateImageDisplayedRotation(
+      syncImageRotationChannel(
         state,
         // When a rotation override has been computed, pass it along (null clears interpolation); otherwise leave undefined.
         hasRotationOverride ? rotationOverride != null ? rotationOverride : null : void 0
       );
     }
+    registerImageBoundsInHitTestTree(sprite, state);
     resultOut.isUpdated = true;
     return true;
   };
@@ -24512,6 +26483,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;
@@ -24541,11 +26516,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;
@@ -24622,6 +26599,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;
@@ -24630,6 +26608,9 @@ const createSpriteLayer = (options) => {
         updated = true;
       }
     }
+    if (needsHitTestRefresh) {
+      refreshSpriteHitTestBounds(sprite);
+    }
     if (isRequiredRender) {
       return "isRequiredRender";
     }
@@ -24653,34 +26634,6 @@ const createSpriteLayer = (options) => {
         return true;
     }
   };
-  const updateBulk = (updateBulkList) => {
-    let updatedCount = 0;
-    let isRequiredRender = false;
-    updateBulkList.forEach((update) => {
-      const result = updateSpriteInternal(update.spriteId, update);
-      switch (result) {
-        case "notfound":
-        // Sprite missing; nothing to do for this entry.
-        case "ignored":
-          break;
-        case "updated":
-          updatedCount++;
-          break;
-        // When rendering must occur because of this update
-        case "isRequiredRender":
-          ensureRenderTargetEntries();
-          scheduleRender();
-          updatedCount++;
-          isRequiredRender = true;
-          break;
-      }
-    });
-    if (isRequiredRender) {
-      ensureRenderTargetEntries();
-      scheduleRender();
-    }
-    return updatedCount;
-  };
   const mutateSprites = (sourceItems, mutator) => {
     if (sourceItems.length === 0) {
       return 0;
@@ -24693,6 +26646,10 @@ const createSpriteLayer = (options) => {
       isUpdated: false
     };
     const updateObject = {
+      isEnabled: void 0,
+      location: void 0,
+      interpolation: void 0,
+      tag: void 0,
       getImageIndexMap: () => {
         const map2 = /* @__PURE__ */ new Map();
         currentSprite.images.forEach((inner, subLayer) => {
@@ -24886,9 +26843,23 @@ const createSpriteLayer = (options) => {
     updateSpriteImage,
     removeSpriteImage,
     updateSprite,
-    updateBulk,
     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
   };
@@ -24897,6 +26868,7 @@ const createSpriteLayer = (options) => {
 exports.BETTER_TEXTURE_FILTERING_OPTIONS = BETTER_TEXTURE_FILTERING_OPTIONS;
 exports.DEFAULT_TEXTURE_FILTERING_OPTIONS = DEFAULT_TEXTURE_FILTERING_OPTIONS;
 exports.STANDARD_SPRITE_SCALING_OPTIONS = STANDARD_SPRITE_SCALING_OPTIONS;
+exports.SvgSizeResolutionError = SvgSizeResolutionError;
 exports.UNLIMITED_SPRITE_SCALING_OPTIONS = UNLIMITED_SPRITE_SCALING_OPTIONS;
 exports.applyAutoRotation = applyAutoRotation;
 exports.calculatePerspectiveRatio = calculatePerspectiveRatio;
@@ -24907,6 +26879,8 @@ exports.compileShader = compileShader;
 exports.createImageStateFromInit = createImageStateFromInit;
 exports.createShaderProgram = createShaderProgram;
 exports.createSpriteLayer = createSpriteLayer;
+exports.loadImageBitmap = loadImageBitmap;
 exports.multiplyMatrixAndVector = multiplyMatrixAndVector;
 exports.projectLngLatToClipSpace = projectLngLatToClipSpace;
+exports.readImageBitmap = readImageBitmap;
 //# sourceMappingURL=index.cjs.map