canvas-globe 1.2.0 → 1.4.0

package/src/geo-globe.js

@@ -1,6 +1,6 @@
 /**
  * canvas-globe: interactive globe & world map on a 2D canvas.
- * No dependencies, no WebGL, no network calls, no API keys.
+ * No dependencies, no WebGL, no required network calls, no API keys.
  */
 import { world as bundledWorld } from "./data/world.js";
 import { themes, countryPalette } from "./themes.js";
@@ -8,6 +8,7 @@ import { presets, presetKeys } from "./presets.js";
 import { locateViewer, locateViewerPrecise } from "./viewer.js";
 import { recordCanvas, downloadBlob, canRecord } from "./recorder.js";
 import { SphereTexture } from "./texture.js";
+import { TileLayer } from "./tiles.js";
 import { Media, drawFitted } from "./media.js";
 import { scenes, sceneKeys } from "./scenes.js";
 import { exportSize } from "./export.js";
@@ -15,7 +16,7 @@ import {
   getLicensePresentation,
   reportLicenseStatus,
 } from "./license.js";
-import { D2R, R2D, TAU, clamp, wrapLon, resolveProjection, projectionBounds, ortho, orthoInverse, greatCircle, circleAround, distanceMeters, subsolarPoint, pointInGeometry, geometryBounds, normalizeShapes, withAlpha } from "./geo.js";
+import { D2R, R2D, TAU, clamp, wrapLon, resolveProjection, projectionBounds, ortho, orthoInverse, greatCircle, circleAround, distanceMeters, subsolarPoint, pointInGeometry, geometryBounds, normalizeShapes, withAlpha, colorScale, hexBinPoints } from "./geo.js";
 
 const DEFAULTS = {
   licenseKey: null,
@@ -31,6 +32,7 @@ const DEFAULTS = {
   countryPalette: null,
   texture: null,
   textureQuality: "auto",
+  tileLayer: null,
   focus: null,
   countryMedia: null,
   annotations: null,
@@ -40,6 +42,7 @@ const DEFAULTS = {
   timeline: null,
   transparentBackground: false,
   heatmap: false,
+  hexBins: false,
   spikes: false,
   labels: false,
   legend: null,
@@ -104,6 +107,7 @@ const phaseOf = (fx, ms) => {
 const defaultTooltip = (target, kind) => {
   if (kind === "country") return target.name || String(target.id ?? "");
   if (kind === "cluster") return `${target.count} in this area`;
+  if (kind === "hex-bin") return `${target.markerCount} markers, value ${target.value}`;
   const name = target.city || target.name || target.label;
   const count = target.count != null ? `: ${target.count}` : "";
   return name ? `${name}${count}` : `${target.lat.toFixed(2)}, ${target.lon.toFixed(2)}${count}`;
@@ -149,6 +153,7 @@ export class GeoGlobe {
     this._story = null;
     this._viewer = null;
     this._texture = null;
+    this._tileLayer = null;
     this._media = new Map();
     this._markerMedia = new Map();
     this._counterShown = null;
@@ -164,6 +169,7 @@ export class GeoGlobe {
     this._applyWorld();
     this._applyMarkers(this.o.markers);
     this._applyTexture();
+    this._applyTileLayer();
     this._applyMedia();
     this._watchMotion();
     this._bind();
@@ -334,6 +340,7 @@ export class GeoGlobe {
     if ("ariaLabel" in patch) this.canvas.setAttribute("aria-label", this.o.ariaLabel);
     if ("projection" in patch || "latRange" in patch) this._bbox = null;
     if ("texture" in patch) this._applyTexture();
+    if ("tileLayer" in patch) this._applyTileLayer();
     if ("countryMedia" in patch) this._applyMedia();
     if ("theme" in patch) this._cssCache = null;
     if ("focus" in patch) this._resolveFocus();
@@ -401,6 +408,11 @@ export class GeoGlobe {
     return this.setOptions({ texture: source });
   }
 
+  /** Optional XYZ overview tiles. Pass null to remove the layer. */
+  setTileLayer(source) {
+    return this.setOptions({ tileLayer: source });
+  }
+
   /* ---------------------------- country focus ---------------------------- */
 
   /**
@@ -897,6 +909,8 @@ export class GeoGlobe {
     this._media.clear();
     for (const media of this._markerMedia.values()) media.destroy?.();
     this._markerMedia.clear();
+    this._tileLayer?.destroy?.();
+    this._tileLayer = null;
     this._tip = null;
     this._live = null;
     this._licenseHits = [];
@@ -963,6 +977,26 @@ export class GeoGlobe {
     this._texture = new SphereTexture(source, { onLoad: () => this.invalidate() });
   }
 
+  _applyTileLayer() {
+    const source = this.o.tileLayer;
+    if (!source) {
+      this._tileLayer?.destroy?.();
+      this._tileLayer = null;
+      this._tileLayerFor = null;
+      return;
+    }
+    if (this._tileLayerFor === source) return;
+    this._tileLayer?.destroy?.();
+    this._tileLayerFor = source;
+    if (source instanceof TileLayer) {
+      this._tileLayer = source;
+      source._onLoad = () => this.invalidate();
+    } else {
+      this._tileLayer = new TileLayer(source, { onLoad: () => this.invalidate() });
+    }
+    this._dirty = true;
+  }
+
   /** Rebuilds the per-country media map, reusing sources that did not change. */
   _applyMedia() {
     const spec = this.o.countryMedia || {};
@@ -1399,7 +1433,7 @@ export class GeoGlobe {
         this._cursor();
         this._dirty = true;
         const target = marker || this._hoveredCountry;
-        this._showTip(marker ? (marker.cluster ? "cluster" : "marker") : this._hoveredCountry ? "country" : null, target);
+        this._showTip(marker ? (marker.hexBin ? "hex-bin" : marker.cluster ? "cluster" : "marker") : this._hoveredCountry ? "country" : null, target);
       } else if (this._tipVisible) {
         this._placeTip();
       }
@@ -2204,6 +2238,23 @@ export class GeoGlobe {
     ctx.restore();
   }
 
+  _paintTileAttribution(w, h) {
+    const text = this._tileLayer?.attribution;
+    if (!text || !this._tileLayer.ready) return;
+    const { ctx } = this;
+    ctx.save();
+    ctx.font = "500 10px Inter,system-ui,sans-serif";
+    ctx.textAlign = "right";
+    ctx.textBaseline = "bottom";
+    const width = Math.min(w - 16, ctx.measureText(text).width + 12);
+    const x = w - 8, y = h - 8;
+    ctx.fillStyle = "rgba(7, 12, 22, 0.72)";
+    ctx.fillRect(x - width, y - 16, width, 18);
+    ctx.fillStyle = "rgba(255,255,255,0.9)";
+    ctx.fillText(text, x - 6, y - 3, width - 12);
+    ctx.restore();
+  }
+
   _licenseRect(ctx, x, y, width, height, radius) {
     ctx.beginPath();
     if (typeof ctx.roundRect === "function") ctx.roundRect(x, y, width, height, radius);
@@ -2587,6 +2638,87 @@ export class GeoGlobe {
     ctx.restore();
   }
 
+  /** Aggregate projected markers into an interactive hexagonal density layer. */
+  _paintHexBins(pts, t, cx, cy, globeRadius, w, h) {
+    const o = this.o.hexBins === true ? {} : this.o.hexBins;
+    const { ctx } = this;
+    const radius = Math.max(4, o.radius ?? 18);
+    const padding = clamp(o.padding ?? 1.5, 0, radius * 0.45);
+    const drawRadius = radius - padding;
+    const minValue = Math.max(0, o.minValue ?? 1);
+    const metric = o.value === "count" ? "count" : "value";
+    const bins = hexBinPoints(pts, radius).filter((bin) => {
+      if (bin[metric] < minValue) return false;
+      if (this.o.mode === "globe") return Math.hypot(bin.x - cx, bin.y - cy) <= globeRadius + drawRadius;
+      return bin.x >= -drawRadius && bin.x <= w + drawRadius && bin.y >= -drawRadius && bin.y <= h + drawRadius;
+    });
+    const max = Math.max(1, ...bins.map((bin) => bin[metric]));
+    const range = Array.isArray(o.colorRange) && o.colorRange.length > 1
+      ? o.colorRange
+      : [t.ocean[0], o.color || t.marker];
+    const domain = range.map((_, index) => max * index / (range.length - 1));
+    const scale = colorScale(domain, range);
+    const hits = [];
+
+    ctx.save();
+    if (this.o.mode === "globe") {
+      ctx.beginPath();
+      ctx.arc(cx, cy, globeRadius, 0, TAU);
+      ctx.clip();
+    } else {
+      ctx.beginPath();
+      ctx.rect(0, 0, w, h);
+      ctx.clip();
+    }
+
+    ctx.lineJoin = "round";
+    for (const bin of bins) {
+      const value = bin[metric];
+      ctx.beginPath();
+      for (let i = 0; i < 6; i++) {
+        const angle = (60 * i - 30) * D2R;
+        const x = bin.x + drawRadius * Math.cos(angle);
+        const y = bin.y + drawRadius * Math.sin(angle);
+        i ? ctx.lineTo(x, y) : ctx.moveTo(x, y);
+      }
+      ctx.closePath();
+      ctx.globalAlpha = clamp(o.opacity ?? 0.82, 0, 1);
+      ctx.fillStyle = scale(value) || o.color || t.marker;
+      ctx.fill();
+      if ((o.strokeWidth ?? 0.8) > 0) {
+        ctx.globalAlpha = 1;
+        ctx.strokeStyle = o.stroke || withAlpha(t.label, 0.3);
+        ctx.lineWidth = o.strokeWidth ?? 0.8;
+        ctx.stroke();
+      }
+      if (o.showCount && drawRadius >= 10) {
+        ctx.globalAlpha = 1;
+        ctx.fillStyle = o.labelColor || t.label;
+        ctx.font = `600 ${Math.max(9, Math.min(13, drawRadius * 0.7))}px Inter,system-ui,sans-serif`;
+        ctx.textAlign = "center";
+        ctx.textBaseline = "middle";
+        ctx.fillText(String(value), bin.x, bin.y);
+      }
+      hits.push({
+        marker: {
+          hexBin: true,
+          count: bin.count,
+          value: bin.value,
+          markerCount: bin.count,
+          markers: bin.markers,
+          lon: bin.lon,
+          lat: bin.lat,
+        },
+        x: bin.x,
+        y: bin.y,
+        r: drawRadius,
+      });
+    }
+    ctx.restore();
+    this._lastHexBins = bins;
+    return hits;
+  }
+
   /** Spike height for a marker, as a fraction of the globe radius. */
   _spikeLift(m) {
     if (!this.o.spikes) return 0;
@@ -2899,7 +3031,8 @@ export class GeoGlobe {
       ctx.fillRect(cx - r, cy - r, r * 2, r * 2);
     }
 
-    const textured = this._texture && this._texture.draw(ctx, cx, cy, r, this.lon, this.lat, this._textureOptions());
+    let textured = !!(this._texture && this._texture.draw(ctx, cx, cy, r, this.lon, this.lat, this._textureOptions()));
+    textured = !!(this._tileLayer?.draw(ctx, cx, cy, r, this.lon, this.lat, this._textureOptions()) || textured);
 
     if (this.o.graticule) {
       ctx.strokeStyle = t.graticule;
@@ -2967,9 +3100,11 @@ export class GeoGlobe {
       pts.push({ m, x: cx + x, y: cy + y, depth: 0.65 + c * 0.35 });
     }
     if (this.o.heatmap) this._paintHeatmap(pts, t);
+    const binHits = this.o.hexBins ? this._paintHexBins(pts, t, cx, cy, r, w, h) : [];
     if (this.o.spikes) this._paintSpikes(t, cx, cy, r, w, h, null);
     this._paintViewerAccuracy(t, cx, cy, r, null);
-    const hits = this._paintMarkers(pts, t);
+    const showMarkers = !this.o.hexBins || (this.o.hexBins !== true && this.o.hexBins.hideMarkers === false);
+    const hits = [...binHits, ...(showMarkers ? this._paintMarkers(pts, t) : [])];
     if (this.o.labels) this._paintLabels(pts, t, cx, cy, r, w, h);
     this._paintAnnotations(t);
     this._paintPings(t);
@@ -2977,6 +3112,7 @@ export class GeoGlobe {
     this._paintCounter(t, w, h);
     this._paintTitle(t, w, h);
     this._paintWatermark(t, w, h);
+    this._paintTileAttribution(w, h);
     return hits;
   }
 
@@ -2996,7 +3132,14 @@ export class GeoGlobe {
       ctx.fillRect(0, 0, w, h);
     }
 
-    const textured = this._texture && this._texture.drawFlat(ctx, fwd, w, h);
+    const flatTextureOptions = {
+      ...this._textureOptions(),
+      inv: v.inv,
+      latRange: this.o.latRange,
+      key: `${this.o.projection}:${this.lon.toFixed(5)}:${this.lat.toFixed(5)}:${this._zoom.toFixed(5)}`,
+    };
+    let textured = !!(this._texture && this._texture.drawFlat(ctx, fwd, w, h, flatTextureOptions));
+    textured = !!(this._tileLayer?.drawFlat(ctx, fwd, w, h, flatTextureOptions) || textured);
 
     if (this.o.graticule) {
       ctx.strokeStyle = t.graticule;
@@ -3044,9 +3187,11 @@ export class GeoGlobe {
       pts.push({ m, x, y, depth: 1 });
     }
     if (this.o.heatmap) this._paintHeatmap(pts, t);
+    const binHits = this.o.hexBins ? this._paintHexBins(pts, t, 0, 0, 0, w, h) : [];
     if (this.o.spikes) this._paintSpikes(t, 0, 0, 0, w, h, fwd);
     this._paintViewerAccuracy(t, 0, 0, 0, fwd);
-    const hits = this._paintMarkers(pts, t);
+    const showMarkers = !this.o.hexBins || (this.o.hexBins !== true && this.o.hexBins.hideMarkers === false);
+    const hits = [...binHits, ...(showMarkers ? this._paintMarkers(pts, t) : [])];
     if (this.o.labels) this._paintLabels(pts, t, 0, 0, 0, w, h);
     this._paintAnnotations(t);
     this._paintPings(t);
@@ -3054,6 +3199,7 @@ export class GeoGlobe {
     this._paintCounter(t, w, h);
     this._paintTitle(t, w, h);
     this._paintWatermark(t, w, h);
+    this._paintTileAttribution(w, h);
     return hits;
   }
 

package/src/geo.js

@@ -254,6 +254,76 @@ export const withAlpha = (color, a) => {
   return color;
 };
 
+/**
+ * Aggregates projected points into a pointy-top hexagonal grid.
+ *
+ * The input is deliberately renderer-shaped (`{ x, y, depth, m }`) so the
+ * same helper works after either globe or flat-map projection. Each returned
+ * bin preserves its source markers for tooltips, clicks, and custom details.
+ */
+export const hexBinPoints = (points = [], radius = 18) => {
+  const size = Math.max(1, Number(radius) || 18);
+  const sqrt3 = Math.sqrt(3);
+  const cells = new Map();
+
+  const roundAxial = (q, r) => {
+    let x = q;
+    let z = r;
+    let y = -x - z;
+    let rx = Math.round(x);
+    let ry = Math.round(y);
+    let rz = Math.round(z);
+    const dx = Math.abs(rx - x);
+    const dy = Math.abs(ry - y);
+    const dz = Math.abs(rz - z);
+    if (dx > dy && dx > dz) rx = -ry - rz;
+    else if (dy > dz) ry = -rx - rz;
+    else rz = -rx - ry;
+    return [rx, rz];
+  };
+
+  for (const point of points) {
+    if (!Number.isFinite(point?.x) || !Number.isFinite(point?.y)) continue;
+    const q = (sqrt3 / 3 * point.x - point.y / 3) / size;
+    const r = (2 * point.y / 3) / size;
+    const [hq, hr] = roundAxial(q, r);
+    const key = `${hq}:${hr}`;
+    let cell = cells.get(key);
+    if (!cell) {
+      cell = {
+        q: hq,
+        r: hr,
+        x: size * sqrt3 * (hq + hr / 2),
+        y: size * 1.5 * hr,
+        count: 0,
+        value: 0,
+        depth: 0,
+        lon: 0,
+        lat: 0,
+        weight: 0,
+        markers: [],
+      };
+      cells.set(key, cell);
+    }
+    const marker = point.m || {};
+    const value = Number(marker.count);
+    const weight = Number.isFinite(value) && value > 0 ? value : 1;
+    cell.count += 1;
+    cell.value += weight;
+    cell.depth = Math.max(cell.depth, Number(point.depth) || 0);
+    cell.lon += (Number(marker.lon) || 0) * weight;
+    cell.lat += (Number(marker.lat) || 0) * weight;
+    cell.weight += weight;
+    cell.markers.push(marker);
+  }
+
+  return [...cells.values()].map((cell) => ({
+    ...cell,
+    lon: cell.weight ? cell.lon / cell.weight : 0,
+    lat: cell.weight ? cell.lat / cell.weight : 0,
+  }));
+};
+
 const parseRGB = (color) => {
   if (color.startsWith("#")) {
     const hex = color.length === 4 ? color.replace(/#(.)(.)(.)/, "#$1$1$2$2$3$3") : color;

package/src/index.js

@@ -15,6 +15,7 @@ export { fromCSV, fromRows, parseCSV, geocode, countryPoint } from "./csv.js";
 export { locateViewer, locateViewerPrecise, timeZoneLocation, countryLocation, placeLocation } from "./viewer.js";
 export { recordCanvas, downloadBlob, canRecord, supportedRecordingType } from "./recorder.js";
 export { SphereTexture } from "./texture.js";
+export { TileLayer, tileUrl } from "./tiles.js";
 export { Media, drawFitted } from "./media.js";
 export {
   DEFAULT_LICENSE_KEY,

package/src/texture.js

@@ -103,7 +103,7 @@ export class SphereTexture {
         out[o] = pixels[s] * k;
         out[o + 1] = pixels[s + 1] * k;
         out[o + 2] = pixels[s + 2] * k;
-        out[o + 3] = 255;
+        out[o + 3] = pixels[s + 3];
       }
     }
     this._ctx.putImageData(this._image, 0, 0);
@@ -111,10 +111,45 @@ export class SphereTexture {
     return true;
   }
 
-  /** Paints the whole texture into a flat-map viewport. */
-  drawFlat(ctx, fwd, w, h) {
+  /** Paints the texture into a flat-map viewport, respecting its projection. */
+  drawFlat(ctx, fwd, w, h, options = {}) {
+    if (!this.ready) return false;
+    const { inv, step = 2, key = "", latRange = [90, -90] } = options;
+    if (inv) {
+      const size = Math.max(1, Number(step) || 1);
+      const width = Math.max(1, Math.ceil(w / size));
+      const height = Math.max(1, Math.ceil(h / size));
+      const cacheKey = `${width}:${height}:${key}:${latRange[0]}:${latRange[1]}`;
+      if (!this._flatProjected || this._flatKey !== cacheKey) {
+        this._flatProjected = makeSurface(width, height);
+        if (!this._flatProjected) return false;
+        this._flatCtx = this._flatProjected.getContext("2d");
+        this._flatImage = this._flatCtx.createImageData(width, height);
+        const out = this._flatImage.data;
+        const [north, south] = latRange;
+        for (let y = 0, offset = 0; y < height; y++) {
+          for (let x = 0; x < width; x++, offset += 4) {
+            const geo = inv((x + 0.5) * size, (y + 0.5) * size);
+            if (!geo || !Number.isFinite(geo[0]) || !Number.isFinite(geo[1]) || geo[1] > north || geo[1] < south) {
+              out[offset + 3] = 0;
+              continue;
+            }
+            const u = Math.max(0, Math.min(this.tw - 1, Math.floor((((geo[0] + 180) % 360 + 360) % 360) * (this.tw / 360))));
+            const v = Math.max(0, Math.min(this.th - 1, Math.floor(((90 - geo[1]) / 180) * this.th)));
+            const source = (v * this.tw + u) * 4;
+            out[offset] = this.pixels[source];
+            out[offset + 1] = this.pixels[source + 1];
+            out[offset + 2] = this.pixels[source + 2];
+            out[offset + 3] = this.pixels[source + 3];
+          }
+        }
+        this._flatCtx.putImageData(this._flatImage, 0, 0);
+        this._flatKey = cacheKey;
+      }
+      ctx.drawImage(this._flatProjected, 0, 0, w, h);
+      return true;
+    }
     if (!this.ready || !this._surface2) {
-      if (!this.ready) return false;
       this._surface2 = makeSurface(this.tw, this.th);
       if (!this._surface2) return false;
       const c = this._surface2.getContext("2d");

package/src/tiles.js

@@ -0,0 +1,227 @@
+/**
+ * Optional XYZ raster tiles composed into an equirectangular texture.
+ *
+ * Nothing is requested unless a tile layer is configured. The deliberately
+ * small default request ceiling keeps this suitable for globe and overview-map
+ * backgrounds, rather than pretending to be a full slippy-map engine.
+ */
+import { SphereTexture } from "./texture.js";
+
+const makeTileSurface = (width, height) => {
+  if (typeof OffscreenCanvas !== "undefined") return new OffscreenCanvas(width, height);
+  if (typeof document === "undefined") return null;
+  const canvas = document.createElement("canvas");
+  canvas.width = width;
+  canvas.height = height;
+  return canvas;
+};
+
+const isTilePromise = (value) => value && typeof value.then === "function";
+const isTileDrawable = (value) => value && typeof value === "object" && (
+  Number(value.naturalWidth || value.videoWidth || value.width) > 0
+);
+
+export const tileUrl = (template, { x, y, z }) => String(template)
+  .replaceAll("{z}", String(z))
+  .replaceAll("{x}", String(x))
+  .replaceAll("{y}", String(y))
+  .replaceAll("{-y}", String((2 ** z) - y - 1));
+
+const tileSourceFrom = (spec) => {
+  if (typeof spec === "string" || typeof spec === "function") return spec;
+  return spec?.getTile || spec?.url || spec?.source || null;
+};
+
+export class TileLayer {
+  constructor(input, { onLoad } = {}) {
+    const spec = typeof input === "object" && input && !isTileDrawable(input) ? input : { source: input };
+    this.spec = spec;
+    this.zoom = Math.max(0, Math.floor(spec.zoom ?? 2));
+    this.tileSize = Math.max(16, Math.floor(spec.tileSize ?? 256));
+    this.opacity = Math.max(0, Math.min(1, Number(spec.opacity ?? 1)));
+    this.attribution = spec.attribution || "";
+    this.crossOrigin = "crossOrigin" in spec ? spec.crossOrigin : "anonymous";
+    this.maxTiles = Math.max(1, Math.floor(spec.maxTiles ?? 64));
+    this.total = (2 ** this.zoom) ** 2;
+    this.loaded = 0;
+    this.failed = 0;
+    this.ready = false;
+    this.error = null;
+    this.cache = new Map();
+    this._source = tileSourceFrom(input);
+    this._onLoad = onLoad;
+    this._destroyed = false;
+    this._refreshQueued = false;
+
+    if (!this._source) {
+      this.error = new TypeError("canvas-globe: tileLayer requires url, source, or getTile");
+      return;
+    }
+    if (this.total > this.maxTiles) {
+      this.error = new RangeError(`canvas-globe: tileLayer zoom ${this.zoom} needs ${this.total} tiles; raise maxTiles to allow it`);
+      spec.onError?.(this.error, null);
+      return;
+    }
+
+    const side = this.tileSize * (2 ** this.zoom);
+    const maxWidth = Math.max(this.tileSize, Math.floor(spec.maxWidth ?? 2048));
+    const width = Math.min(side, maxWidth);
+    this._scale = width / side;
+    this._surface = makeTileSurface(width, width);
+    this._ctx = this._surface?.getContext?.("2d") || null;
+    if (!this._ctx) {
+      this.error = new Error("canvas-globe: tileLayer needs a canvas-capable browser");
+      return;
+    }
+    this._loadAll();
+  }
+
+  _loadAll() {
+    const side = 2 ** this.zoom;
+    for (let y = 0; y < side; y++) {
+      for (let x = 0; x < side; x++) this._load({ x, y, z: this.zoom });
+    }
+  }
+
+  _resolve(tile) {
+    if (typeof this._source === "function") return this._source(tile);
+    return tileUrl(this._source, tile);
+  }
+
+  _load(tile) {
+    const key = `${tile.z}/${tile.x}/${tile.y}`;
+    if (this.cache.has(key)) return this.cache.get(key);
+    const entry = { ...tile, key, status: "loading", source: null, error: null };
+    this.cache.set(key, entry);
+    let resolved;
+    try {
+      resolved = this._resolve(tile);
+    } catch (error) {
+      this._fail(entry, error);
+      return entry;
+    }
+    const finish = (source) => this._loadSource(source, entry);
+    if (isTilePromise(resolved)) resolved.then(finish, (error) => this._fail(entry, error));
+    else finish(resolved);
+    return entry;
+  }
+
+  _loadSource(source, entry) {
+    if (this._destroyed) return;
+    if (isTileDrawable(source)) {
+      this._draw(source, entry);
+      return;
+    }
+    if (typeof source !== "string" || !source) {
+      this._fail(entry, new TypeError(`canvas-globe: tile ${entry.key} did not resolve to an image or URL`));
+      return;
+    }
+    if (typeof Image === "undefined") {
+      this._fail(entry, new Error("canvas-globe: tile URLs need the browser Image API"));
+      return;
+    }
+    const image = new Image();
+    if (this.crossOrigin != null) image.crossOrigin = this.crossOrigin;
+    image.onload = () => this._draw(image, entry);
+    image.onerror = () => this._fail(entry, new Error(`canvas-globe: could not load tile ${entry.key}`));
+    image.src = source;
+    entry.source = source;
+  }
+
+  _draw(source, entry) {
+    if (this._destroyed || entry.status !== "loading") return;
+    const size = this.tileSize * this._scale;
+    try {
+      this._ctx.drawImage(source, entry.x * size, entry.y * size, size, size);
+      entry.status = "loaded";
+      entry.source = source;
+      this.loaded++;
+      this._queueRefresh();
+    } catch (error) {
+      this._fail(entry, error);
+    }
+  }
+
+  _fail(entry, error) {
+    if (this._destroyed || entry.status === "failed") return;
+    entry.status = "failed";
+    entry.error = error instanceof Error ? error : new Error(String(error));
+    this.failed++;
+    if (!this.error) this.error = entry.error;
+    this.spec.onError?.(entry.error, { x: entry.x, y: entry.y, z: entry.z });
+    if (this.loaded) this._queueRefresh();
+    this._onLoad?.(this);
+  }
+
+  _queueRefresh() {
+    const complete = this.loaded + this.failed;
+    const interval = Math.max(1, Math.ceil(this.total / 4));
+    if (complete < this.total && this.loaded % interval !== 0) return;
+    if (this._refreshQueued) return;
+    this._refreshQueued = true;
+    queueMicrotask(() => {
+      this._refreshQueued = false;
+      if (this._destroyed || !this.loaded) return;
+      const surface = this._toEquirectangular();
+      const texture = new SphereTexture(surface, {
+        maxWidth: surface.width,
+        onLoad: () => this._onLoad?.(this),
+      });
+      if (texture.ready) {
+        this.texture = texture;
+        this.ready = true;
+      } else if (texture.error) {
+        this.error = texture.error;
+        this.spec.onError?.(texture.error, null);
+      }
+      this._onLoad?.(this);
+    });
+  }
+
+  /** XYZ rows use Web Mercator; the globe texture expects linear latitude. */
+  _toEquirectangular() {
+    const width = this._surface.width;
+    const height = Math.max(1, Math.round(width / 2));
+    const surface = makeTileSurface(width, height);
+    const ctx = surface.getContext("2d");
+    const sourceHeight = this._surface.height;
+    for (let y = 0; y < height; y++) {
+      const lat = 90 - ((y + 0.5) / height) * 180;
+      const sin = Math.sin((Math.max(-85.05112878, Math.min(85.05112878, lat)) * Math.PI) / 180);
+      const mercatorY = 0.5 - Math.log((1 + sin) / (1 - sin)) / (4 * Math.PI);
+      const sourceY = Math.max(0, Math.min(sourceHeight - 1, mercatorY * sourceHeight));
+      ctx.drawImage(this._surface, 0, sourceY, width, 1, 0, y, width, 1);
+    }
+    return surface;
+  }
+
+  draw(ctx, ...args) {
+    if (!this.ready || !this.texture || this.opacity <= 0) return false;
+    ctx.save();
+    ctx.globalAlpha *= this.opacity;
+    const drew = this.texture.draw(ctx, ...args);
+    ctx.restore();
+    return drew;
+  }
+
+  drawFlat(ctx, ...args) {
+    if (!this.ready || !this.texture || this.opacity <= 0) return false;
+    ctx.save();
+    ctx.globalAlpha *= this.opacity;
+    const drew = this.texture.drawFlat(ctx, ...args);
+    ctx.restore();
+    return drew;
+  }
+
+  get stats() {
+    return { loaded: this.loaded, failed: this.failed, total: this.total, cached: this.cache.size };
+  }
+
+  destroy() {
+    this._destroyed = true;
+    this.cache.clear();
+    this.texture = null;
+    this._surface = null;
+    this._ctx = null;
+  }
+}

package/src/version.js

@@ -1,2 +1,2 @@
 // Keep in sync with package.json. Release checks enforce this value.
-export const CANVAS_GLOBE_VERSION = "1.2.0";
+export const CANVAS_GLOBE_VERSION = "1.4.0";

package/types/element.d.ts

@@ -1,8 +1,8 @@
-import type { Arc, CountryShape, GeoGlobe, GeoGlobeOptions, Marker, ClusterMarker, FlyToOptions } from "./index.js";
+import type { Arc, CountryShape, GeoGlobe, GeoGlobeOptions, Marker, ClusterMarker, HexBinMarker, FlyToOptions } from "./index.js";
 
 export interface GeoGlobeEventMap {
-  "geo-hover": CustomEvent<{ marker: Marker | ClusterMarker | null; pos: { x: number; y: number } | null }>;
-  "geo-click": CustomEvent<{ marker: Marker | ClusterMarker; pos: { x: number; y: number } }>;
+  "geo-hover": CustomEvent<{ marker: Marker | ClusterMarker | HexBinMarker | null; pos: { x: number; y: number } | null }>;
+  "geo-click": CustomEvent<{ marker: Marker | ClusterMarker | HexBinMarker; pos: { x: number; y: number } }>;
   "geo-country-hover": CustomEvent<{ country: CountryShape | null; pos: { x: number; y: number } | null }>;
   "geo-country-click": CustomEvent<{ country: CountryShape; pos: { x: number; y: number } }>;
   "geo-render": CustomEvent<{ globe: GeoGlobe }>;