solid-map-gl 2.0.1 → 2.2.0

package/dist/index.jsx

@@ -1,16 +1,23 @@
 // src/components/MapGL/index.tsx
 import {
   createSignal,
-  createEffect,
+  createEffect as createEffect2,
   onMount,
   onCleanup,
   on
 } from "solid-js";
+import { isServer } from "solid-js/web";
 
 // src/components/MapProvider/index.tsx
-import { createContext, useContext } from "solid-js";
+import { createContext, useContext, createEffect } from "solid-js";
 import { createStore } from "solid-js/store";
-var defaultState = { map: null, mapLib: null, isMapLibre: false };
+var defaultState = {
+  map: null,
+  mapLib: null,
+  isMapLibre: false,
+  constants: {},
+  themeVersion: 0
+};
 var MapContext = createContext([defaultState]);
 var useMapContext = () => useContext(MapContext);
 var MapProvider = (props) => {
@@ -18,6 +25,10 @@ var MapProvider = (props) => {
   props.map && setState("map", props.map);
   props.mapLib && setState("mapLib", props.mapLib);
   setState("isMapLibre", !!props.isMapLibre);
+  setState("constants", props.constants || {});
+  setState("themeVersion", props.themeVersion || 0);
+  createEffect(() => setState("constants", props.constants || {}));
+  createEffect(() => setState("themeVersion", props.themeVersion || 0));
   return <MapContext.Provider value={[state]}>{props.children}</MapContext.Provider>;
 };
 
@@ -218,6 +229,79 @@ var rasterStyleList = {
   }
 };
 
+// src/tilesSettled.ts
+var nextFrame = () => new Promise((resolve) => requestAnimationFrame(() => resolve()));
+var hasActiveFadeTransition = (map) => {
+  try {
+    return !!map.style?.hasTransitions?.();
+  } catch {
+    return false;
+  }
+};
+function pollTilesLoaded(map, timeout) {
+  return new Promise((resolve) => {
+    const deadline = Date.now() + timeout;
+    const poll = () => {
+      if (map.areTilesLoaded()) {
+        resolve(true);
+        return;
+      }
+      if (Date.now() >= deadline) {
+        resolve(false);
+        return;
+      }
+      setTimeout(poll, 100);
+    };
+    poll();
+  });
+}
+async function settleAfterIdle(map, options = {}) {
+  const { timeout = 1e4, fadeMargin = 400 } = options;
+  await pollTilesLoaded(map, timeout);
+  map.triggerRepaint();
+  await nextFrame();
+  await nextFrame();
+  if (fadeMargin > 0) {
+    const fadeDeadline = Date.now() + Math.max(fadeMargin, 2e3);
+    while (hasActiveFadeTransition(map) && Date.now() < fadeDeadline) {
+      map.triggerRepaint();
+      await nextFrame();
+    }
+    await new Promise((resolve) => setTimeout(resolve, fadeMargin));
+    map.triggerRepaint();
+    await nextFrame();
+    await nextFrame();
+  }
+}
+function waitForIdleAndSettle(map, options = {}) {
+  return new Promise((resolve) => {
+    map.once("idle", () => {
+      settleAfterIdle(map, options).then(resolve);
+    });
+  });
+}
+function disableRasterFade(map) {
+  for (const layer of map.getStyle()?.layers ?? []) {
+    try {
+      map.setPaintProperty(layer.id, "raster-fade-duration", 0);
+    } catch {
+    }
+  }
+}
+
+// src/offscreenCapture.ts
+function createCapturer(map, settleOptions) {
+  return {
+    map,
+    waitUntilSettled: () => waitForIdleAndSettle(map, settleOptions),
+    capture: (type = "image/jpeg", quality = 0.92) => map.getCanvas().toDataURL(type, quality),
+    captureWhenSettled: async (type = "image/jpeg", quality = 0.92) => {
+      await waitForIdleAndSettle(map, settleOptions);
+      return map.getCanvas().toDataURL(type, quality);
+    }
+  };
+}
+
 // src/components/MapGL/index.tsx
 var MapGL = (props) => {
   let map;
@@ -226,9 +310,11 @@ var MapGL = (props) => {
   let mutationObserver;
   let mapLib;
   let isMapLibre = false;
+  let tilesLoadedGeneration = 0;
   const [mapLoaded, setMapLoaded] = createSignal(null);
+  const [themeVersion, setThemeVersion] = createSignal(0);
   const [darkMode, setDarkMode] = createSignal(
-    typeof window !== "undefined" && window.matchMedia("(prefers-color-scheme: dark)").matches || typeof document !== "undefined" && document.body.classList.contains("dark")
+    !isServer && (window.matchMedia("(prefers-color-scheme: dark)").matches || document.body.classList.contains("dark"))
   );
   let interruptingEase = false;
   let expectingOwnEcho = false;
@@ -257,7 +343,11 @@ var MapGL = (props) => {
       projection: props.options?.projection,
       container: mapRef,
       style: getStyle(props.options?.style, props.darkStyle),
-      fitBoundsOptions: { padding: props.viewport?.padding }
+      fitBoundsOptions: { padding: props.viewport?.padding },
+      // Required for capture()/toDataURL() to read back anything from the canvas at all — forced
+      // regardless of `options` since getting this wrong doesn't degrade capture, it silently
+      // breaks it (an all-transparent/blank image, no error).
+      ...props.offscreen ? { preserveDrawingBuffer: true } : {}
     });
     map.debug = props.debug;
     map.debugEvents = props.debugEvents;
@@ -289,9 +379,30 @@ var MapGL = (props) => {
         }
       }
     });
+    if (props.onTilesLoaded) {
+      const timeout = props.tilesLoadedTimeout ?? 1e4;
+      const fadeMargin = props.tilesLoadedFadeMargin ?? 400;
+      map.on("idle", () => {
+        const generation = ++tilesLoadedGeneration;
+        settleAfterIdle(map, { timeout, fadeMargin }).then(() => {
+          if (generation !== tilesLoadedGeneration) return;
+          debug("Tiles settled");
+          props.onTilesLoaded();
+        });
+      });
+    }
     map.once("load", () => {
       setMapLoaded(map);
       debug("Map loaded");
+      if (props.offscreen) {
+        if (props.offscreen.disableRasterFade !== false) disableRasterFade(map);
+        props.onCapturerReady?.(
+          createCapturer(map, {
+            timeout: props.tilesLoadedTimeout ?? 1e4,
+            fadeMargin: props.tilesLoadedFadeMargin ?? 400
+          })
+        );
+      }
       ["mousedown", "touchstart", "wheel"].forEach(
         (event) => map.on(
           event,
@@ -304,16 +415,19 @@ var MapGL = (props) => {
           (evt) => !evt.rotate && props.onUserInteraction?.(false)
         )
       );
-      const darkTheme = typeof window !== "undefined" && window?.matchMedia("(prefers-color-scheme: dark)");
+      const darkTheme = !isServer && window.matchMedia("(prefers-color-scheme: dark)");
       darkTheme?.addEventListener("change", () => {
         setDarkMode(darkTheme.matches);
+        setThemeVersion((v) => v + 1);
         debug("Set dark theme to:", darkTheme.matches?.toString());
       });
       mutationObserver = new MutationObserver(() => {
-        const darkTheme2 = document.body.classList.contains("dark");
+        const darkTheme2 = document.documentElement.classList.contains("dark") || document.body.classList.contains("dark");
         setDarkMode(darkTheme2);
+        setThemeVersion((v) => v + 1);
         debug("Set theme to:", darkTheme2);
       });
+      mutationObserver.observe(document.documentElement, { attributes: true });
       mutationObserver.observe(document.body, { attributes: true });
       if (!props.disableResize) {
         resizeObserver = new ResizeObserver(() => {
@@ -368,7 +482,7 @@ var MapGL = (props) => {
       });
     });
   });
-  createEffect(
+  createEffect2(
     on(
       () => props.viewport,
       (vp) => {
@@ -397,7 +511,7 @@ var MapGL = (props) => {
       { defer: true }
     )
   );
-  createEffect(() => {
+  createEffect2(() => {
     const loadedMap = mapLoaded();
     if (typeof loadedMap?.setConfigProperty !== "function") {
       if (loadedMap && props.config && Object.keys(props.config).length) {
@@ -415,13 +529,13 @@ var MapGL = (props) => {
       debug(`Set Config (${id}:${key}) to:`, value);
     }
   });
-  createEffect(() => {
+  createEffect2(() => {
     const proj = props.options?.projection;
     if (!map || !proj) return;
     map.setProjection(proj);
     debug("Set Projection to:", proj);
   });
-  createEffect(() => {
+  createEffect2(() => {
     const cur = props.cursorStyle;
     if (!map || !cur) return;
     map.getCanvas().style.cursor = cur;
@@ -436,7 +550,7 @@ var MapGL = (props) => {
     });
     return list;
   };
-  createEffect((prev) => {
+  createEffect2((prev) => {
     const style = getStyle(props.options?.style, props.darkStyle);
     if (map?.isStyleLoaded() && prev !== style) {
       const oldStyle = map.getStyle();
@@ -469,7 +583,7 @@ var MapGL = (props) => {
     "showPadding",
     "showOverdrawInspector"
   ].forEach((item) => {
-    createEffect(() => {
+    createEffect2(() => {
       const prop = props[item];
       if (!map || !prop) return;
       map[item] = prop;
@@ -479,6 +593,7 @@ var MapGL = (props) => {
   onCleanup(() => {
     resizeObserver?.disconnect();
     mutationObserver?.disconnect();
+    tilesLoadedGeneration++;
     map?.remove();
     debug("Map removed");
   });
@@ -487,9 +602,22 @@ var MapGL = (props) => {
     id={props.id}
     class={props?.class}
     classList={props?.classList}
-    style={{ width: "100%", height: "100%", ...props.style }}
+    style={props.offscreen ? {
+      position: "fixed",
+      left: "-99999px",
+      top: "-99999px",
+      width: `${props.offscreen.width}px`,
+      height: `${props.offscreen.height}px`,
+      ...props.style
+    } : { width: "100%", height: "100%", ...props.style }}
+  >
+      {mapLoaded() && <MapProvider
+    map={mapLoaded()}
+    mapLib={mapLib}
+    isMapLibre={isMapLibre}
+    constants={props.constants}
+    themeVersion={themeVersion()}
   >
-      {mapLoaded() && <MapProvider map={mapLoaded()} mapLib={mapLib} isMapLibre={isMapLibre}>
           <style>{`.overlay{position:relative;width:100%;height:100%;pointer-events:none}:where(.overlay>*){pointer-events:auto}`}</style>
           <div class="overlay">{props.children}</div>
         </MapProvider>}
@@ -499,7 +627,7 @@ var MapGL = (props) => {
 // src/components/Source/index.tsx
 import {
   onCleanup as onCleanup2,
-  createEffect as createEffect2,
+  createEffect as createEffect3,
   createContext as createContext2,
   useContext as useContext2,
   createUniqueId
@@ -537,14 +665,14 @@ var Source = (props) => {
   debug("Add Source:", props.id);
   switch (anySource().type) {
     case "geojson":
-      createEffect2(() => {
+      createEffect3(() => {
         const data = anySource().data;
         ctx.map.getSource(props.id).setData(data || {});
         debug("Update GeoJSON Data:", props.id);
       });
       break;
     case "image":
-      createEffect2(() => {
+      createEffect3(() => {
         const url = anySource().url;
         const coords = anySource().coordinates;
         ctx.map.getSource(props.id).updateImage(url, coords);
@@ -552,7 +680,7 @@ var Source = (props) => {
       });
       break;
     case "vector":
-      createEffect2(() => {
+      createEffect3(() => {
         const url = anySource().url;
         const tiles = anySource().tiles;
         const source = ctx.map.getSource(props.id);
@@ -561,7 +689,7 @@ var Source = (props) => {
       });
       break;
     case "raster":
-      createEffect2(() => {
+      createEffect3(() => {
         const src = lookup(anySource().url);
         const source = ctx.map.getSource(props.id);
         src.url ? source.setUrl(src.url) : source.setTiles(src.tiles);
@@ -584,7 +712,7 @@ var Source = (props) => {
 // src/components/Layer/index.tsx
 import {
   onCleanup as onCleanup3,
-  createEffect as createEffect3,
+  createEffect as createEffect4,
   createMemo,
   createUniqueId as createUniqueId2
 } from "solid-js";
@@ -653,7 +781,70 @@ var layoutStyles = [
   "text-writing-mode"
 ];
 
+// src/colors.ts
+var probe;
+var toRgbString = (cssColor) => {
+  probe ??= document.body.appendChild(document.createElement("div"));
+  probe.style.cssText = "position:absolute;visibility:hidden;pointer-events:none";
+  probe.style.color = "";
+  probe.style.color = cssColor;
+  return probe.style.color ? getComputedStyle(probe).color : void 0;
+};
+var tailwindName = /^[a-z]+-\d{2,3}$/;
+var nativelySupported = /^(rgb|rgba|hsl|hsla)\(/i;
+var cssColorFunction = /^[a-z-]+\(/i;
+var classProbe;
+var bgClassPair = /^bg-[a-z]+-\d{2,3}(?:\s+dark:bg-[a-z]+-\d{2,3})?$/;
+var resolveClassPair = (value) => {
+  classProbe ??= document.body.appendChild(document.createElement("div"));
+  classProbe.style.cssText = "position:absolute;visibility:hidden;pointer-events:none";
+  classProbe.className = value;
+  const bg = getComputedStyle(classProbe).backgroundColor;
+  classProbe.className = "";
+  return bg && bg !== "rgba(0, 0, 0, 0)" ? bg : value;
+};
+var resolveColor = (value) => {
+  if (bgClassPair.test(value)) return resolveClassPair(value);
+  if (tailwindName.test(value)) {
+    const raw = getComputedStyle(document.documentElement).getPropertyValue(`--color-${value}`).trim();
+    return raw && toRgbString(raw) || value;
+  }
+  if (cssColorFunction.test(value) && !nativelySupported.test(value)) {
+    return toRgbString(value) || value;
+  }
+  return value;
+};
+var toRgbaComponents = (value) => {
+  const rgb = toRgbString(resolveColor(value)) ?? value;
+  const match = rgb.match(/rgba?\(([^)]+)\)/i);
+  if (!match) return [0, 0, 0, 1];
+  const [r, g, b, a = 1] = match[1].split(",").map(Number);
+  return [r, g, b, a];
+};
+
 // src/components/Layer/index.tsx
+var PULSE_DEFAULTS = {
+  property: "icon-halo-width",
+  from: 0,
+  to: 8,
+  duration: 1500,
+  waveform: "out"
+};
+var PULSE_RAMP_FRACTION = 0.75;
+var easeOutQuad = (t) => 1 - (1 - t) * (1 - t);
+var pulseShape = (elapsed, duration, waveform) => {
+  const phase = elapsed % duration / duration;
+  if (waveform === "in-out") return (1 - Math.cos(phase * Math.PI * 2)) / 2;
+  const ramp = Math.min(phase / PULSE_RAMP_FRACTION, 1);
+  return easeOutQuad(ramp);
+};
+var lerpColor = (from, to, t) => {
+  const r = Math.round(from[0] + (to[0] - from[0]) * t);
+  const g = Math.round(from[1] + (to[1] - from[1]) * t);
+  const b = Math.round(from[2] + (to[2] - from[2]) * t);
+  const a = from[3] + (to[3] - from[3]) * t;
+  return `rgba(${r}, ${g}, ${b}, ${a})`;
+};
 var diff = (newProps = {}, prevProps = {}) => {
   const keys = /* @__PURE__ */ new Set([...Object.keys(newProps), ...Object.keys(prevProps)]);
   return [...keys].reduce((acc, key) => {
@@ -665,26 +856,43 @@ var diff = (newProps = {}, prevProps = {}) => {
   }, []);
 };
 var newKey = (key, type) => (key.startsWith(type) || key.startsWith("icon") || key.startsWith("text") ? "" : type + "-") + key.replace(/[A-Z]/g, (s) => "-" + s.toLowerCase());
-var updateStyle = (oldStyle) => {
+var resolveColor2 = (key, value) => key.endsWith("color") && typeof value === "string" ? resolveColor(value) : value;
+var constantRef = /^@(.+)$/;
+var resolveConstant = (key, value, constants, debug) => {
+  if (typeof value !== "string") return value;
+  const match = value.match(constantRef);
+  if (!match) return value;
+  const resolved = constants[match[1]];
+  if (resolved === void 0) {
+    debug(`Unknown constant "@${match[1]}" referenced by "${key}" \u2014 leaving unresolved`);
+    return value;
+  }
+  return resolved;
+};
+var updateStyle = (oldStyle, constants = {}, debug = () => {
+}) => {
   if (!oldStyle) return;
   let layout = {};
   let paint = {};
   let style = {};
+  const resolvePaint = (key, value) => resolveColor2(key, resolveConstant(key, value, constants, debug));
   Object.entries(oldStyle).forEach(([key, value]) => {
     if (baseStyle.includes(key)) style[key] = value;
     else {
       const nk = newKey(key, oldStyle.type);
-      layoutStyles.includes(nk) ? layout[nk] = value : paint[nk] = value;
+      layoutStyles.includes(nk) ? layout[nk] = resolveConstant(nk, value, constants, debug) : paint[nk] = resolvePaint(nk, value);
     }
   });
   if (oldStyle.paint)
-    Object.entries(oldStyle.paint).forEach(
-      ([key, value]) => paint[newKey(key, oldStyle.type)] = value
-    );
+    Object.entries(oldStyle.paint).forEach(([key, value]) => {
+      const nk = newKey(key, oldStyle.type);
+      paint[nk] = resolvePaint(nk, value);
+    });
   if (oldStyle.layout)
-    Object.entries(oldStyle.layout).forEach(
-      ([key, value]) => layout[newKey(key, oldStyle.type)] = value
-    );
+    Object.entries(oldStyle.layout).forEach(([key, value]) => {
+      const nk = newKey(key, oldStyle.type);
+      layout[nk] = resolveConstant(nk, value, constants, debug);
+    });
   return { ...style, paint, layout };
 };
 var Layer = (props) => {
@@ -699,7 +907,7 @@ var Layer = (props) => {
   );
   ctx.map.addLayer(
     props.customLayer || {
-      ...updateStyle(props.style),
+      ...updateStyle(props.style, ctx.constants, debug),
       id: layerId,
       source: sourceId,
       // `slot` is Mapbox Standard-Style-only — MapLibre has no equivalent (see docs/dev-notes.md)
@@ -723,8 +931,9 @@ var Layer = (props) => {
       });
     }
   });
-  createEffect3((prev) => {
-    const style = updateStyle(props.style);
+  createEffect4((prev) => {
+    ctx.themeVersion;
+    const style = updateStyle(props.style, ctx.constants, debug);
     if (style === prev) return;
     if (style.layout !== prev?.layout)
       diff(style.layout, prev?.layout).forEach(
@@ -740,8 +949,8 @@ var Layer = (props) => {
       ctx.map.setFilter(layerId, style.filter, { validate: false });
     debug("Update Layer Style:", layerId);
     return style;
-  }, updateStyle(props.style));
-  createEffect3((prev) => {
+  }, updateStyle(props.style, ctx.constants, debug));
+  createEffect4((prev) => {
     if (props.visible === prev) return;
     ctx.map.setLayoutProperty(
       layerId,
@@ -752,19 +961,19 @@ var Layer = (props) => {
     debug(`Update Visibility (${layerId}):`, props.visible.toString());
     return props.visible;
   }, props.visible);
-  createEffect3((prev) => {
+  createEffect4((prev) => {
     if (getBeforeId() === prev) return prev;
     ctx.map.moveLayer(layerId, getBeforeId());
     debug(`Update Layer Z-Index (${layerId}):`, getBeforeId());
     return getBeforeId();
   }, getBeforeId());
-  createEffect3(async () => {
+  createEffect4(async () => {
     if (!props.filter) return;
     !ctx.map.isStyleLoaded() && await ctx.map.once("styledata");
     ctx.map.setFilter(layerId, props.filter);
     debug(`Update Filter (${layerId}):`, props.filter);
   });
-  createEffect3(async () => {
+  createEffect4(async () => {
     if (!props.featureState || props.featureState.id === null) return;
     !ctx.map.isStyleLoaded() && await ctx.map.once("styledata");
     ctx.map.removeFeatureState({
@@ -780,6 +989,44 @@ var Layer = (props) => {
       props.featureState.state
     );
   });
+  createEffect4(() => {
+    if (!props.pulse) return;
+    const configs = props.pulse === true ? [{}] : Array.isArray(props.pulse) ? props.pulse : [props.pulse];
+    const resolved = configs.map((config) => {
+      const { property, from, to, duration, waveform } = {
+        ...PULSE_DEFAULTS,
+        ...config
+      };
+      const isColor = typeof from === "string" || typeof to === "string";
+      const [a, b] = waveform === "in" ? [to, from] : [from, to];
+      return {
+        property,
+        duration,
+        waveform,
+        isColor,
+        fromNum: isColor ? 0 : a,
+        toNum: isColor ? 0 : b,
+        fromRgba: isColor ? toRgbaComponents(a) : null,
+        toRgba: isColor ? toRgbaComponents(b) : null
+      };
+    });
+    const start = performance.now();
+    let frameId;
+    const loop = (now) => {
+      const elapsed = now - start;
+      resolved.forEach((cfg) => {
+        const t = pulseShape(elapsed, cfg.duration, cfg.waveform);
+        const value = cfg.isColor ? lerpColor(cfg.fromRgba, cfg.toRgba, t) : cfg.fromNum + (cfg.toNum - cfg.fromNum) * t;
+        ctx.map.setPaintProperty(layerId, cfg.property, value, {
+          validate: false
+        });
+      });
+      frameId = window.requestAnimationFrame(loop);
+    };
+    frameId = window.requestAnimationFrame(loop);
+    debug(`Start Pulse (${layerId}):`, props.pulse);
+    onCleanup3(() => window.cancelAnimationFrame(frameId));
+  });
   onCleanup3(() => ctx.map?.getLayer(layerId) && ctx.map?.removeLayer(layerId));
   return props.children;
 };
@@ -934,10 +1181,10 @@ var Layer3D = (props) => {
 };
 
 // src/components/Atmosphere/index.tsx
-import { onCleanup as onCleanup5, createEffect as createEffect4 } from "solid-js";
+import { onCleanup as onCleanup5, createEffect as createEffect5 } from "solid-js";
 var Atmosphere = (props) => {
   const [ctx] = useMapContext();
-  createEffect4(() => {
+  createEffect5(() => {
     if (ctx.isMapLibre) ctx.map.setSky?.(props.style || {});
     else ctx.map.setFog(props.style || {});
   });
@@ -953,7 +1200,7 @@ var Atmosphere = (props) => {
 
 // src/components/Terrain/index.tsx
 import {
-  createEffect as createEffect5,
+  createEffect as createEffect6,
   createUniqueId as createUniqueId4,
   onCleanup as onCleanup6
 } from "solid-js";
@@ -970,7 +1217,7 @@ var Terrain = (props) => {
     });
     ctx.map.sourceIdList.push(sourceId);
   }
-  createEffect5(() => {
+  createEffect6(() => {
     ctx.map.setTerrain({
       exaggeration: props.exaggeration || 1,
       source: props?.source || sourceId
@@ -981,13 +1228,13 @@ var Terrain = (props) => {
 };
 
 // src/components/Control/index.tsx
-import { createSignal as createSignal3, createEffect as createEffect7, splitProps, untrack } from "solid-js";
+import { createSignal as createSignal3, createEffect as createEffect8, splitProps, untrack } from "solid-js";
 
 // src/lib/createMapControl.ts
-import { createEffect as createEffect6, onCleanup as onCleanup7 } from "solid-js";
+import { createEffect as createEffect7, onCleanup as onCleanup7 } from "solid-js";
 var useControlPosition = (control, position) => {
   const [ctx] = useMapContext();
-  createEffect6(() => {
+  createEffect7(() => {
     const c = control();
     const pos = position?.();
     if (!c) return;
@@ -1014,7 +1261,7 @@ var Control = (props) => {
     ["logo", ctx.mapLib.LogoControl],
     ["terrain", ctx.mapLib.TerrainControl]
   ]);
-  createEffect7(() => {
+  createEffect8(() => {
     untrack(
       () => control() && ctx.map.hasControl(control()) && ctx.map.removeControl(control())
     );
@@ -1027,7 +1274,7 @@ var Control = (props) => {
 };
 
 // src/components/Marker/index.tsx
-import { onCleanup as onCleanup8, createEffect as createEffect8, splitProps as splitProps2 } from "solid-js";
+import { onCleanup as onCleanup8, createEffect as createEffect9, splitProps as splitProps2 } from "solid-js";
 var Marker = (props) => {
   if (!props.lngLat) throw new Error("Marker - lngLat is required");
   const [update, create_popup, create_marker] = splitProps2(
@@ -1039,7 +1286,7 @@ var Marker = (props) => {
   let marker = null;
   let popup = null;
   const LNGLAT = update.lngLat;
-  createEffect8(() => {
+  createEffect9(() => {
     if (!ctx.map) return;
     popup?.remove();
     popup = new ctx.mapLib.Popup({
@@ -1047,31 +1294,31 @@ var Marker = (props) => {
       focusAfterOpen: false,
       ...create_popup.popup
     }).on("open", () => create_popup.onOpen?.()).on("close", () => create_popup.onClose?.());
-    createEffect8(() => {
+    createEffect9(() => {
       if (update.children === void 0) return;
       typeof update.children === "string" ? popup?.setHTML(update.children) : popup?.setDOMContent(update.children);
       marker?.setPopup(popup);
     });
-    createEffect8(
+    createEffect9(
       () => update.showPopup !== popup?.isOpen() && marker?.togglePopup()
     );
   });
-  createEffect8(() => {
+  createEffect9(() => {
     if (!ctx.map) return;
     marker?.remove();
     marker = new ctx.mapLib.Marker(create_marker.options).on("dragstart", () => create_marker.onDragStart?.()).on("dragend", () => create_marker.onDragEnd?.()).on("drag", () => create_marker.onDrag?.(marker?.getLngLat().toArray())).setPopup(popup).setLngLat(LNGLAT).addTo(ctx.map);
-    createEffect8(
+    createEffect9(
       () => update.showPopup !== popup?.isOpen() && marker?.togglePopup()
     );
   });
-  createEffect8(() => marker?.setLngLat(update.lngLat));
-  createEffect8(() => marker?.setDraggable(update.draggable));
+  createEffect9(() => marker?.setLngLat(update.lngLat));
+  createEffect9(() => marker?.setDraggable(update.draggable));
   onCleanup8(() => marker?.remove());
   return null;
 };
 
 // src/components/Popup/index.tsx
-import { onCleanup as onCleanup9, createEffect as createEffect9, splitProps as splitProps3 } from "solid-js";
+import { onCleanup as onCleanup9, createEffect as createEffect10, splitProps as splitProps3 } from "solid-js";
 var Popup = (props) => {
   if (!props.trackPointer && !props.lngLat)
     throw new Error("Popup - lngLat or trackPointer is required");
@@ -1082,7 +1329,7 @@ var Popup = (props) => {
   ]);
   const [ctx] = useMapContext();
   let popup;
-  createEffect9(() => {
+  createEffect10(() => {
     if (!ctx.map) return;
     popup?.remove();
     popup = new ctx.mapLib.Popup({
@@ -1090,10 +1337,10 @@ var Popup = (props) => {
       focusAfterOpen: false,
       ...create.options
     }).on("open", () => create.onOpen?.()).on("close", () => create.onClose?.()).addTo(ctx.map);
-    createEffect9(
+    createEffect10(
       () => update.trackPointer ? popup.trackPointer() : popup.setLngLat(update.lngLat)
     );
-    createEffect9(
+    createEffect10(
       () => typeof update.children === "string" ? popup.setHTML(update.children) : popup.setDOMContent(update.children)
     );
   });
@@ -1105,63 +1352,189 @@ var Popup = (props) => {
 import {
   onCleanup as onCleanup10,
   createSignal as createSignal4,
-  createEffect as createEffect10,
+  createEffect as createEffect11,
   untrack as untrack2
 } from "solid-js";
+
+// src/components/Image/sdf.ts
+var INF = 1e20;
+var ALPHA_TABLE = new Float64Array(256);
+for (let i = 0; i < 256; i++) {
+  const d = 0.5 - Math.pow(i / 255, 1 / 2.2);
+  ALPHA_TABLE[i] = d * Math.abs(d);
+}
+ALPHA_TABLE[255] = -INF;
+function edt1d(grid, offset, stride, length3, f, v, z) {
+  v[0] = 0;
+  z[0] = -INF;
+  z[1] = INF;
+  f[0] = grid[offset];
+  for (let q = 1, k = 0, s = 0; q < length3; q++) {
+    f[q] = grid[offset + q * stride];
+    const q2 = q * q;
+    do {
+      const r = v[k];
+      s = (f[q] - f[r] + q2 - r * r) / (q - r) / 2;
+    } while (s <= z[k] && --k > -1);
+    k++;
+    v[k] = q;
+    z[k] = s;
+    z[k + 1] = INF;
+  }
+  for (let q = 0, k = 0; q < length3; q++) {
+    while (z[k + 1] < q) k++;
+    const r = v[k];
+    const qr = q - r;
+    grid[offset + q * stride] = f[r] + qr * qr;
+  }
+}
+function edt(data, width, height, f, v, z) {
+  for (let x = 0; x < width; x++) edt1d(data, x, width, height, f, v, z);
+  for (let y = 0; y < height; y++) edt1d(data, y * width, 1, width, f, v, z);
+}
+var sdfPadding = ({ radius = 8 } = {}) => Math.ceil(radius);
+function toSDF(imageData, { radius = 8, cutoff = 0.25 } = {}) {
+  const { width, height } = imageData;
+  const len = width * height;
+  const gridOuter = new Float64Array(len).fill(INF);
+  const gridInner = new Float64Array(len);
+  const size = Math.max(width, height);
+  const f = new Float64Array(size);
+  const v = new Uint16Array(size);
+  const z = new Float64Array(size + 1);
+  const src = imageData.data;
+  for (let i = 0, j = 3; i < len; i++, j += 4) {
+    const a = src[j];
+    if (a === 0) continue;
+    const t = ALPHA_TABLE[a];
+    gridOuter[i] = Math.max(0, t);
+    gridInner[i] = Math.max(0, -t);
+  }
+  edt(gridOuter, width, height, f, v, z);
+  edt(gridInner, width, height, f, v, z);
+  const scale = 255 / radius;
+  const base = 255 * (1 - cutoff);
+  const out = new Uint8ClampedArray(len * 4);
+  for (let i = 0, j = 0; i < len; i++, j += 4) {
+    const d = Math.sqrt(gridOuter[i]) - Math.sqrt(gridInner[i]);
+    const value = Math.max(0, Math.min(255, Math.round(base - scale * d)));
+    out[j] = out[j + 1] = out[j + 2] = 255;
+    out[j + 3] = value;
+  }
+  return { width, height, data: out };
+}
+
+// src/components/Image/shapes.ts
 var PATTERN = {
   diagonal_l: { size: 20, path: "M20 0 0 20M-10 10 10-10M10 30 30 10" },
   diagonal_r: { size: 20, path: "M0 0 20 20M30 10 10-10M10 30-10 10" },
   horizontal: { size: 14, path: "M7 0V20" },
   vertical: { size: 14, path: "M0 7H20" },
+  // A single centered "+" per tile, tiling into a repeating grid of crosses — not to be
+  // confused with `SYMBOL.cross` (a single bold "+" icon) below.
   cross: { size: 18, path: "M9 0V18M0 9H18" },
   hash: { size: 30, path: "M15 0 30 15 15 30 0 15Z" },
   chevron_h: { size: 20, path: "M-5 5 0 10 10 0 20 10 25 5M0 30 10 20 20 30" },
   chevron_v: { size: 20, path: "M5-5 10 0 0 10 10 20 5 25M25 15 20 10 25 5" },
   square: { size: 20, path: "M8 8H12V12H8Z", fill: true },
   hex: { size: 50, path: "M0 0V50L50 25ZM50 0V50L0 25ZM25 0V50" },
+  // Two arcs swept almost all the way around (`A2.5 2.5 0 1 1 ...` to a point a hair past the
+  // start) rather than a `<circle>`, since this path is later stroked/filled via `Path2D`,
+  // which has no dedicated circle primitive. A single dot per tile — not to be confused with
+  // `SYMBOL.circle` (a single full-bleed circle icon) below.
   circle: {
     size: 25,
     path: "M8 10A2.5 2.5 0 118.01 10M18 15A2.5 2.5 0 1018.01 15",
     fill: true
-  }
+  },
+  // `horizontal` and `vertical` combined into one crossed-line tile.
+  grid: { size: 20, path: "M10 0V20M0 10H20" },
+  // Two rows of offset (running-bond) bricks per tile, so the offset continues correctly
+  // when tiles stack — row two's joints fall at the quarter-points, not centered, to match
+  // a real brick course rather than just checkerboarding.
+  brick: {
+    size: 40,
+    path: "M0 0H40M0 20H40M0 40H40M0 0V20M20 0V20M40 0V20M10 20V40M30 20V40"
+  },
+  // Two wavy horizontal lines per tile (quadratic-bezier "hump" repeated via the `T` shorthand),
+  // for the wave/water fill texture common in geologic and land-cover maps.
+  wave: { size: 20, path: "M0 5Q5 0 10 5T20 5M0 15Q5 10 10 15T20 15" }
 };
 var patternList = Object.keys(PATTERN);
+var svg = (body) => `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">${body}</svg>`;
+var SYMBOL = {
+  square: svg('<rect x="8" y="8" width="48" height="48" fill="#000"/>'),
+  circle: svg('<circle cx="32" cy="32" r="28" fill="#000"/>'),
+  triangle: svg('<polygon points="32,6 60,56 4,56" fill="#000"/>'),
+  diamond: svg('<polygon points="32,4 60,32 32,60 4,32" fill="#000"/>'),
+  pentagon: svg('<polygon points="32,4 59,23 48,55 16,55 5,23" fill="#000"/>'),
+  hexagon: svg('<polygon points="32,4 56,18 56,46 32,60 8,46 8,18" fill="#000"/>'),
+  // A square with corners cut at 2/7 of its side, the standard construction for a regular
+  // octagon (stop-sign proportions) without resorting to trig.
+  octagon: svg(
+    '<polygon points="20,4 44,4 60,20 60,44 44,60 20,60 4,44 4,20" fill="#000"/>'
+  ),
+  cross: svg(
+    '<polygon points="20,4 44,4 44,20 60,20 60,44 44,44 44,60 20,60 20,44 4,44 4,20 20,20" fill="#000"/>'
+  ),
+  // The same 12-point "+" as `cross` above, rotated 45° about the center.
+  x: svg(
+    '<polygon points="43,4 60,21 49,32 60,43 43,60 32,49 21,60 4,43 15,32 4,21 21,4 32,15" fill="#000"/>'
+  ),
+  // A regular 5-pointed star: outer vertices every 72° (radius 30) alternating with inner
+  // vertices every 72° offset by 36° (radius ~11.5, the usual ratio for a balanced star).
+  star: svg(
+    '<polygon points="32,2 39,23 61,23 43,36 50,56 32,44 14,56 21,36 4,23 25,23" fill="#000"/>'
+  )
+};
+var symbolList = Object.keys(SYMBOL);
+var wrapSymbolPath = (d) => svg(`<path d="${d}" fill="#000"/>`);
+
+// src/components/Image/index.tsx
 var MGL_Image = (props) => {
   const [ctx] = useMapContext();
   const [size, setSize] = createSignal4({ width: 0, height: 0 });
+  let latestImage = null;
   const debug = (text, value) => {
     ctx.map.debug && console.debug("%c[MapGL]", "color: #10b981", text, value || "");
   };
+  const handleStyleLoad = () => {
+    if (!latestImage || !ctx.map || ctx.map.hasImage(props.id)) return;
+    ctx.map.addImage(props.id, latestImage.data, latestImage.ops);
+    debug("Re-Add Image:", props.id);
+  };
+  ctx.map.on("style.load", handleStyleLoad);
   onCleanup10(() => {
+    ctx.map?.off("style.load", handleStyleLoad);
     ctx.map?.hasImage(props.id) && ctx.map?.removeImage(props.id);
     debug("Remove Image:", props.id);
   });
-  createEffect10(() => {
+  createEffect11(() => {
     if (!props.id) throw new Error("Image - ID is required");
-    if (!props.source && !props.pattern)
-      throw new Error("Image - Image or Pattern is required");
-    const ops = props.pattern ? { pixelRatio: 2, ...props.options } : props.options;
-    _loadImage(props.source || _createPattern(props.pattern), (data) => {
+    if (!props.source && !props.pattern && !props.symbol)
+      throw new Error("Image - Image, Pattern or Symbol is required");
+    const pixelRatio = Math.max(1, Math.round(window.devicePixelRatio || 2));
+    const ops = props.pattern ? { pixelRatio, ...props.options } : props.sdf ? { ...props.options, sdf: true } : props.options;
+    const symbolSource = props.symbol && (SYMBOL[props.symbol] || (props.symbol.trimStart().startsWith("<svg") ? props.symbol : wrapSymbolPath(props.symbol)));
+    _loadImage(props.source || symbolSource || _createPattern(props.pattern, pixelRatio), (data, autoPixelRatio) => {
+      const finalOps = autoPixelRatio ? { ...ops, pixelRatio: autoPixelRatio } : ops;
       const { width, height } = data;
       if (ctx.map && !ctx.map.hasImage(props.id))
-        ctx.map.addImage(props.id, data, ops);
+        ctx.map.addImage(props.id, data, finalOps);
       if (!props.pattern && untrack2(() => width === size().width && height === size().height)) {
         ctx.map.updateImage(props.id, data);
         ctx.map.triggerRepaint();
       } else {
         ctx.map.removeImage(props.id);
-        ctx.map.addImage(props.id, data, ops);
+        ctx.map.addImage(props.id, data, finalOps);
       }
       setSize({ width, height });
+      latestImage = { data, ops: finalOps };
       debug("Add Image:", props.id);
-      ctx.map.on("style.load", () => {
-        if (ctx.map.hasImage(props.id)) return;
-        ctx.map.addImage(props.id, data, ops);
-        debug("Re-Add Image:", props.id);
-      });
     });
   });
   const _loadImage = (image, callback) => {
+    const sdfOpts = props.sdf ? typeof props.sdf === "object" ? props.sdf : {} : null;
     if (typeof image == "string" && image?.trimStart().startsWith("<svg")) {
       image = new DOMParser().parseFromString(image, "image/svg+xml").childNodes[0];
     }
@@ -1184,36 +1557,63 @@ var MGL_Image = (props) => {
         const img = new Image();
         img.crossOrigin = "Anonymous";
         img.onload = () => {
+          const floorScale = Math.max(1, 50 / Math.min(img.width, img.height));
+          const pixelRatio = props.options?.pixelRatio ?? Math.max(1, Math.round(window.devicePixelRatio || 1));
+          const scale = floorScale * pixelRatio;
+          const padding = sdfOpts ? sdfPadding(sdfOpts) * pixelRatio : 0;
+          const drawWidth = Math.round(img.width * scale);
+          const drawHeight = Math.round(img.height * scale);
           const canvas = document.createElement("canvas");
-          canvas.width = Math.max(img.width, 50);
-          canvas.height = Math.max(img.height, 50);
+          canvas.width = drawWidth + padding * 2;
+          canvas.height = drawHeight + padding * 2;
           const ctx2 = canvas.getContext("2d");
           ctx2.imageSmoothingEnabled = true;
-          ctx2.drawImage(img, 0, 0, canvas.width, canvas.height);
-          return callback(ctx2.getImageData(0, 0, canvas.width, canvas.height));
+          ctx2.drawImage(img, padding, padding, drawWidth, drawHeight);
+          const imageData2 = ctx2.getImageData(0, 0, canvas.width, canvas.height);
+          return callback(
+            sdfOpts ? toSDF(imageData2, sdfOpts) : imageData2,
+            pixelRatio
+          );
         };
-        img.src = image.trimStart().startsWith("<svg") ? "data:image/svg+xml;charset=utf-8," + image : image;
+        img.onerror = (event) => console.error(`[MapGL] Image "${props.id}" failed to load:`, event);
+        img.src = image.trimStart().startsWith("<svg") ? "data:image/svg+xml;charset=utf-8," + encodeURIComponent(image) : image;
       } else {
-        return callback(imageData);
+        if (!sdfOpts) return callback(imageData);
+        const { width, height } = imageData;
+        const padding = sdfPadding(sdfOpts);
+        const canvas = document.createElement("canvas");
+        canvas.width = width + padding * 2;
+        canvas.height = height + padding * 2;
+        const c = canvas.getContext("2d");
+        c.imageSmoothingEnabled = true;
+        if ("data" in imageData) {
+          c.putImageData(imageData, padding, padding);
+        } else {
+          c.drawImage(imageData, padding, padding, width, height);
+        }
+        const pixels = c.getImageData(0, 0, canvas.width, canvas.height);
+        return callback(toSDF(pixels, sdfOpts));
       }
     });
   };
-  const _createPattern = (pattern) => {
+  const _createPattern = (pattern, pixelRatio = 2) => {
     const p = PATTERN[pattern.type];
+    const size2 = p.size * pixelRatio;
     return {
-      width: p.size,
-      height: p.size,
-      data: new Uint8Array(p.size * p.size * 4),
+      width: size2,
+      height: size2,
+      data: new Uint8Array(size2 * size2 * 4),
       onAdd: function() {
-        let canvas = document.createElement("canvas");
-        canvas.width = canvas.height = p.size;
+        const canvas = document.createElement("canvas");
+        canvas.width = canvas.height = size2;
         this.ctx = canvas.getContext("2d", { willReadFrequently: true });
+        this.ctx.scale(pixelRatio, pixelRatio);
       },
       render: function() {
         this.ctx.fillStyle = pattern.background || "transparent";
-        this.ctx.fillRect(0, 0, this.width, this.height);
+        this.ctx.fillRect(0, 0, p.size, p.size);
         this.ctx.strokeStyle = this.ctx.fillStyle = pattern.color || "black";
-        this.ctx.lineWidth = pattern.lineWith || 1;
+        this.ctx.lineWidth = pattern.lineWidth || 1;
         this.ctx.stroke(new Path2D(p.path));
         if (p.fill) this.ctx.fill(new Path2D(p.path));
         this.data = this.ctx.getImageData(0, 0, this.width, this.height).data;
@@ -1225,7 +1625,7 @@ var MGL_Image = (props) => {
 };
 
 // src/components/Camera/index.tsx
-import { createEffect as createEffect11, onCleanup as onCleanup11, createSignal as createSignal5 } from "solid-js";
+import { createEffect as createEffect12, onCleanup as onCleanup11, createSignal as createSignal5 } from "solid-js";
 var lerp = (a, b, t) => a.map((_, idx) => (1 - t) * a[idx] + t * b[idx]);
 var slerp = (a, b, t) => {
   const dotProduct = a.map((_, idx) => a[idx] * b[idx]).reduce((m, n) => m + n);
@@ -1272,7 +1672,7 @@ var Camera = (props) => {
       isReverse = !isReverse;
     animationTime = isReverse ? animationTime - 1e-3 : animationTime + 1e-3;
   };
-  createEffect11(() => {
+  createEffect12(() => {
     props.translate && window.requestAnimationFrame(frame);
   });
   const options = { duration: 1e3, easing: (n) => n };
@@ -1307,7 +1707,7 @@ var Camera = (props) => {
   const onEnd = () => props.rotateGlobe ? rotateGlobe() : rotateViewport();
   ctx.map.on("moveend", onEnd).on("dragend", onEnd);
   let originalCenter;
-  createEffect11(() => {
+  createEffect12(() => {
     if (props.rotateGlobe == void 0) return;
     if (props.rotateGlobe) {
       originalCenter = ctx.map.getCenter();
@@ -1316,7 +1716,7 @@ var Camera = (props) => {
       props.resetWhenStopped ? ctx.map.stop().easeTo({ center: originalCenter }) : ctx.map.stop();
     }
   });
-  createEffect11(() => {
+  createEffect12(() => {
     if (props.rotateViewport == void 0) return;
     props.rotateViewport ? rotateViewport() : props.resetWhenStopped ? ctx.map.stop().resetNorthPitch() : ctx.map.stop();
   });
@@ -1325,10 +1725,10 @@ var Camera = (props) => {
 };
 
 // src/components/Light/index.tsx
-import { onCleanup as onCleanup12, createEffect as createEffect12 } from "solid-js";
+import { onCleanup as onCleanup12, createEffect as createEffect13 } from "solid-js";
 var Light = (props) => {
   const [ctx] = useMapContext();
-  createEffect12(() => ctx.map.setLight(props.style || {}));
+  createEffect13(() => ctx.map.setLight(props.style || {}));
   onCleanup12(() => ctx.map?.setLight(null));
   return null;
 };
@@ -2285,7 +2685,7 @@ var Draw = (props) => {
 };
 
 // src/components/DeckOverlay/index.tsx
-import { createEffect as createEffect13 } from "solid-js";
+import { createEffect as createEffect14 } from "solid-js";
 var DeckOverlay = (props) => {
   const [ctx] = useMapContext();
   let overlay;
@@ -2294,7 +2694,7 @@ var DeckOverlay = (props) => {
     return overlay;
   };
   useControlPosition(control);
-  createEffect13(() => overlay?.setProps(props.props || {}));
+  createEffect14(() => overlay?.setProps(props.props || {}));
   return null;
 };
 export {
@@ -2313,8 +2713,13 @@ export {
   Source,
   Terrain,
   MapGL as default,
+  disableRasterFade,
   patternList,
+  settleAfterIdle,
+  symbolList,
+  toSDF,
   useMapContext,
   useScene,
-  useSourceId
+  useSourceId,
+  waitForIdleAndSettle
 };