canvas-globe 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -6,6 +6,26 @@ All notable changes to this package are documented here. The format follows
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-09-19
+
+### Added
+
+- Added an interactive screen-space hex-bin density layer for globe and map
+  modes, including weighted aggregation, colour ramps, source-marker hit
+  payloads, framework event types, and 5,000-marker performance coverage.
+- Added an Angular SSR and hydration starter with prerendered HTML, a stable
+  canvas shell, client hydration, and project-creator support.
+- Added a reproducible nine-library globe comparison harness for timing,
+  bundle size, package metadata, server-import, and accessibility-surface
+  measurements.
+
+### Fixed
+
+- Prevented the Angular component from creating a CanvasGlobe instance during
+  server rendering.
+- Corrected public TypeScript declarations for story-step overrides and theme
+  options.
+
 ## [1.2.0] - 2026-09-18
 
 ### Added

package/README.md

@@ -35,7 +35,7 @@
 
 [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz_small.svg)](https://stackblitz.com/github/Shree-hari/canvas-globe?startScript=start)
 
-**Start with your stack:** [Vanilla JS](starters/vanilla-vite) | [React + Vite](starters/react-vite) | [Next.js](starters/nextjs-app-router) | [Vue](starters/vue-vite) | [SvelteKit](starters/sveltekit) | [Web Component](starters/web-component-vite)
+**Start with your stack:** [Vanilla JS](starters/vanilla-vite) | [React + Vite](starters/react-vite) | [Next.js](starters/nextjs-app-router) | [Nuxt](starters/nuxt-ssr) | [Vue](starters/vue-vite) | [SvelteKit](starters/sveltekit) | [Angular SSR](starters/angular-ssr) | [Web Component](starters/web-component-vite)
 
 **Install with shadcn:** `npx shadcn@latest add https://canvasglobe.swiftools.com/r/canvas-globe.json`
 
@@ -139,19 +139,19 @@ your existing application rather than installing a second React copy.
 For a plain `<script>` installation, use the versioned UMD build:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/canvas-globe@1.2.0/dist/canvas-globe.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/canvas-globe@1.3.0/dist/canvas-globe.umd.js"></script>
 ```
 
 The same npm release is also available from UNPKG:
 
 ```html
-<script src="https://unpkg.com/canvas-globe@1.2.0/dist/canvas-globe.umd.js"></script>
+<script src="https://unpkg.com/canvas-globe@1.3.0/dist/canvas-globe.umd.js"></script>
 ```
 
 Modern browsers can import the package through an ESM CDN:
 
 ```js
-import { createGlobe } from "https://esm.sh/canvas-globe@1.2.0";
+import { createGlobe } from "https://esm.sh/canvas-globe@1.3.0";
 ```
 
 Pin an exact version in production so a future release cannot change a deployed page unexpectedly.
@@ -171,7 +171,7 @@ import { createGlobe } from "canvas-globe";
 Or drop the UMD build on a page with no build step at all:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/canvas-globe@1.2.0/dist/canvas-globe.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/canvas-globe@1.3.0/dist/canvas-globe.umd.js"></script>
 <canvas id="globe" style="width:520px;aspect-ratio:1"></canvas>
 <script>
   CanvasGlobe.createGlobe(document.getElementById("globe"), {
@@ -381,6 +381,7 @@ included effects. See `types/fx.d.ts` for every option and callback signature.
 | `timeline` | Not set | `{ at }`: hides markers whose `date` has not arrived |
 | `transparentBackground` | `false` | Skip the ocean fill so exports keep an alpha channel |
 | `heatmap` | `false` | Additive density blobs: `{ radius, intensity, color }` |
+| `hexBins` | `false` | Interactive screen-space density cells; see [Hex bins](#hex-bins) |
 | `spikes` | `false` | Bars off the surface, sized by `count`: `{ height, width }` |
 | `labels` | `false` | `"markers"` \| `"countries"` \| `"both"`, with collision avoidance |
 | `legend` | Not set | `{ title, items }` or `{ title, scale, position }` |
@@ -443,6 +444,41 @@ With `cluster: true`, dense areas collapse into a single bubble and your callbac
 `{ cluster: true, count, markers, lat, lon }` instead. Clustering happens in screen space, so it
 re-balances automatically as you zoom.
 
+## Hex bins
+
+Use hex bins when individual markers are too dense to read. CanvasGlobe aggregates the visible,
+projected markers into a pointy-top hexagonal grid, so the density view updates naturally as the
+globe rotates, the map pans, or the user zooms.
+
+```js
+const globe = createGlobe(canvas, {
+  markers: demandPoints,
+  hexBins: {
+    radius: 19,
+    value: "sum",
+    colorRange: ["#dbeafe", "#2563eb", "#172554"],
+    padding: 1.5,
+    showCount: true,
+  },
+  tooltip: (target, kind) => kind === "hex-bin"
+    ? `${target.markerCount} locations, ${target.value} total requests`
+    : target.name,
+  onClick: (target) => {
+    if (target.hexBin) console.log(target.markers);
+  },
+});
+```
+
+Each interactive bin returned to `tooltip`, `onHover`, and `onClick` contains
+`{ hexBin: true, markerCount, count, value, markers, lat, lon }`. The default `value: "sum"` adds
+each marker's `count`; use `value: "count"` to colour by the number of markers. Individual markers
+are hidden by default while the layer is active. Set `hideMarkers: false` to keep them visible.
+
+Available options are `radius`, `minValue`, `value`, `color`, `colorRange`, `opacity`, `stroke`,
+`strokeWidth`, `padding`, `showCount`, `labelColor`, and `hideMarkers`. The same configuration works
+in globe and flat-map modes. Since binning happens after projection, `radius` is measured in screen
+pixels rather than geographic degrees.
+
 ### How accurate is marker placement?
 
 The projection maths is exact: a marker's pixel position matches the closed-form projection to

package/codemeta.json

@@ -5,7 +5,7 @@
   "identifier": "canvas-globe",
   "description": "CanvasGlobe helps developers add interactive 3D globes and flat world maps to JavaScript and React apps with Canvas 2D, without WebGL, map tiles, API keys, or runtime network calls.",
   "url": "https://canvasglobe.swiftools.com/",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "codeRepository": "https://github.com/Shree-hari/canvas-globe",
   "issueTracker": "https://github.com/Shree-hari/canvas-globe/issues",
   "downloadUrl": "https://www.npmjs.com/package/canvas-globe",

package/custom-elements.json

@@ -112,8 +112,8 @@
             { "name": "lat-range", "description": "Serialized latitude range.", "type": { "text": "[number, number]" } }
           ],
           "events": [
-            { "name": "geo-hover", "description": "Fires when the hovered marker changes.", "type": { "text": "CustomEvent<{ marker: Marker | ClusterMarker | null; pos: { x: number; y: number } | null }>" } },
-            { "name": "geo-click", "description": "Fires when a marker is clicked.", "type": { "text": "CustomEvent<{ marker: Marker | ClusterMarker; pos: { x: number; y: number } }>" } },
+            { "name": "geo-hover", "description": "Fires when the hovered marker changes.", "type": { "text": "CustomEvent<{ marker: Marker | ClusterMarker | HexBinMarker | null; pos: { x: number; y: number } | null }>" } },
+            { "name": "geo-click", "description": "Fires when a marker is clicked.", "type": { "text": "CustomEvent<{ marker: Marker | ClusterMarker | HexBinMarker; pos: { x: number; y: number } }>" } },
             { "name": "geo-country-hover", "description": "Fires when the hovered country changes.", "type": { "text": "CustomEvent<{ country: CountryShape | null; pos: { x: number; y: number } | null }>" } },
             { "name": "geo-country-click", "description": "Fires when a country is clicked.", "type": { "text": "CustomEvent<{ country: CountryShape; pos: { x: number; y: number } }>" } },
             { "name": "geo-render", "description": "Fires after CanvasGlobe renders a frame.", "type": { "text": "CustomEvent<{ globe: GeoGlobe }>" } }

package/dist/canvas-globe.umd.js

@@ -640,6 +640,76 @@ 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.
+ */
+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;
@@ -1314,7 +1384,7 @@ function drawFitted(ctx, media, box) {
 }
 
 // Keep in sync with package.json. Release checks enforce this value.
-const CANVAS_GLOBE_VERSION = "1.2.0";
+const CANVAS_GLOBE_VERSION = "1.3.0";
 
 /** Local license-key checks and production-use presentation helpers. */
 
@@ -1477,6 +1547,7 @@ const DEFAULTS = {
   timeline: null,
   transparentBackground: false,
   heatmap: false,
+  hexBins: false,
   spikes: false,
   labels: false,
   legend: null,
@@ -1541,6 +1612,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}`;
@@ -2836,7 +2908,7 @@ 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();
       }
@@ -4024,6 +4096,87 @@ 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;
@@ -4404,9 +4557,11 @@ 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);
@@ -4481,9 +4636,11 @@ 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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canvas-globe",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Build interactive 3D globes and flat world maps in JavaScript, React, Vue, Angular, or Svelte with Canvas 2D and no WebGL.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": {

package/src/geo-globe.js

@@ -15,7 +15,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,
@@ -40,6 +40,7 @@ const DEFAULTS = {
   timeline: null,
   transparentBackground: false,
   heatmap: false,
+  hexBins: false,
   spikes: false,
   labels: false,
   legend: null,
@@ -104,6 +105,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}`;
@@ -1399,7 +1401,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();
       }
@@ -2587,6 +2589,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;
@@ -2967,9 +3050,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);
@@ -3044,9 +3129,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);

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/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.3.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 }>;

package/types/index.d.ts

@@ -32,6 +32,20 @@ export interface ClusterMarker {
   lon: number;
 }
 
+/** Synthetic marker produced by the `hexBins` density layer. */
+export interface HexBinMarker {
+  hexBin: true;
+  /** Number of source markers in the cell. */
+  markerCount: number;
+  /** Number of source markers in the cell. */
+  count: number;
+  /** Sum of source marker `count` values, with missing values treated as 1. */
+  value: number;
+  markers: Marker[];
+  lat: number;
+  lon: number;
+}
+
 export type Coordinate = { lat: number; lon: number } | [lon: number, lat: number];
 
 export interface Arc {
@@ -178,7 +192,7 @@ export interface Handle {
   stop(): void;
 }
 
-export interface StoryStep extends Partial<GeoGlobeOptions> {
+export interface StoryStep extends Omit<Partial<GeoGlobeOptions>, "center" | "zoom"> {
   /** Scroll progress, 0-1. */
   at: number;
   center?: [lon: number, lat: number];
@@ -193,6 +207,31 @@ export interface HeatmapOptions {
   color?: string;
 }
 
+export interface HexBinOptions {
+  /** Hexagon radius in screen pixels. Default 18. */
+  radius?: number;
+  /** Ignore cells below this count or summed value. Default 1. */
+  minValue?: number;
+  /** Colour cells by summed marker values or marker count. Default "sum". */
+  value?: "sum" | "count";
+  /** Single base colour used when `colorRange` is omitted. */
+  color?: string;
+  /** Low-to-high colour ramp. */
+  colorRange?: string[];
+  /** Fill opacity, 0-1. Default 0.82. */
+  opacity?: number;
+  stroke?: string;
+  /** Cell outline width in px. Default 0.8. */
+  strokeWidth?: number;
+  /** Gap inside each cell in px. Default 1.5. */
+  padding?: number;
+  /** Draw the selected count/value inside each cell. Default false. */
+  showCount?: boolean;
+  labelColor?: string;
+  /** Hide individual markers beneath the bins. Default true. */
+  hideMarkers?: boolean;
+}
+
 export interface SpikeOptions {
   /** Tallest spike as a fraction of the globe radius. Default 0.28. */
   height?: number;
@@ -378,7 +417,7 @@ export interface RenderMarkerContext {
   globe: GeoGlobe;
 }
 
-export type TooltipKind = "marker" | "cluster" | "country";
+export type TooltipKind = "marker" | "cluster" | "hex-bin" | "country";
 
 export interface GeoGlobeOptions {
   /** Commercial license key supplied after purchase. */
@@ -387,8 +426,6 @@ export interface GeoGlobeOptions {
   mode?: "globe" | "map";
   /** Flat-map projection. Default "equirectangular". */
   projection?: MapProjection;
-  /** Built-in theme name or a partial theme object. Default "atlas". */
-  theme?: ThemeName | Partial<Theme>;
   /** Named bundle of theme + render style, applied under your own options. */
   preset?: PresetName;
   /** Theme name, a partial theme, "auto" for the OS colour scheme, or "css"
@@ -428,6 +465,8 @@ export interface GeoGlobeOptions {
   transparentBackground?: boolean;
   /** Additive density blobs instead of, or under, markers. */
   heatmap?: boolean | HeatmapOptions;
+  /** Screen-space hexagonal aggregation for dense marker datasets. */
+  hexBins?: boolean | HexBinOptions;
   /** Bars standing off the surface, scaled by each marker's `count`. */
   spikes?: boolean | SpikeOptions;
   /** Text labels with collision avoidance. */
@@ -496,13 +535,13 @@ export interface GeoGlobeOptions {
   /** Frame cap. Default 30. */
   fps?: number;
   /** Built-in tooltip. `true` uses the default text, or pass a formatter. */
-  tooltip?: boolean | ((target: Marker | ClusterMarker | CountryShape, kind: TooltipKind) => string);
+  tooltip?: boolean | ((target: Marker | ClusterMarker | HexBinMarker | CountryShape, kind: TooltipKind) => string);
   /** Honour `prefers-reduced-motion`. Default true. */
   respectReducedMotion?: boolean;
   /** Accessible name for the canvas. */
   ariaLabel?: string;
-  onHover?: (marker: Marker | ClusterMarker | null, position: { x: number; y: number } | null) => void;
-  onClick?: (marker: Marker | ClusterMarker, position: { x: number; y: number }) => void;
+  onHover?: (marker: Marker | ClusterMarker | HexBinMarker | null, position: { x: number; y: number } | null) => void;
+  onClick?: (marker: Marker | ClusterMarker | HexBinMarker, position: { x: number; y: number }) => void;
   onCountryHover?: (country: CountryShape | null, position: { x: number; y: number } | null) => void;
   onCountryClick?: (country: CountryShape, position: { x: number; y: number }) => void;
   onRender?: (instance: GeoGlobe) => void;

package/types/jsr-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 }>;