canvas-globe 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -6,6 +6,39 @@ All notable changes to this package are documented here. The format follows
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-09-19
+
+### Added
+
+- Added opt-in cached XYZ overview tiles with Web Mercator conversion, globe and flat-map
+  reprojection, provider callbacks, request ceilings, graceful failures, CORS-aware export, and
+  attribution painted into every frame.
+
+### Fixed
+
+- Reprojected equirectangular textures correctly in Mercator and Natural Earth map views instead
+  of stretching them to the projected viewport.
+
+## [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,17 +35,19 @@
 
 [![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`
 
 `canvas-globe` is a zero-dependency JavaScript library for an interactive
 **3D globe** and **flat world map** on Canvas 2D. It works with
 vanilla JavaScript, React, Vue, Angular, Svelte, or a Web Component and requires no WebGL, map API
-key, tile service, or runtime network request.
+key, tile service, or runtime network request. Optional XYZ tiles are available when you explicitly
+configure a provider.
 
-- **Zero dependencies:** no WebGL, D3, map tiles, or API keys
-- **Zero network calls:** country geometry ships inside the package
+- **Zero dependencies:** no required WebGL, D3, map tiles, or API keys
+- **Zero required network calls:** country geometry ships inside the package
+- **Optional XYZ tiles:** opt into a cached raster provider for globe and overview-map backgrounds
 - **Interactive:** drag, zoom, pinch, hover, and click
 - **Marker support:** weighted markers, avatars, pulse rings, and clustering
 - **Great-circle arcs:** animated routes clipped at the horizon
@@ -139,19 +141,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.4.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.4.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.4.0";
 ```
 
 Pin an exact version in production so a future release cannot change a deployed page unexpectedly.
@@ -171,7 +173,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.4.0/dist/canvas-globe.umd.js"></script>
 <canvas id="globe" style="width:520px;aspect-ratio:1"></canvas>
 <script>
   CanvasGlobe.createGlobe(document.getElementById("globe"), {
@@ -371,6 +373,7 @@ included effects. See `types/fx.d.ts` for every option and callback signature.
 | `orbits` | `0` | Decorative rings: a count (0-6) or explicit specs |
 | `texture` | Not set | Equirectangular image painted onto the sphere |
 | `textureQuality` | `"auto"` | Pixel step for the texture pass; higher is faster |
+| `tileLayer` | Not set | Optional cached XYZ overview tiles; see [Tile layers](#tile-layers) |
 | `focus` | Not set | Frame one country: `"IN"` or `{ country, isolate, dim, outlineWidth }` |
 | `countryMedia` | Not set | Media clipped to each country, keyed by ISO, id or name |
 | `scene` | Not set | Whole composition: preset plus the layers a job needs |
@@ -381,6 +384,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 +447,76 @@ 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.
+
+## Tile layers
+
+CanvasGlobe does not contact a tile service by default. Set `tileLayer` only when a raster basemap
+adds real value to the product. The same cached tile mosaic is reprojected for the globe,
+equirectangular, Mercator, and Natural Earth views.
+
+```js
+const globe = createGlobe(canvas, {
+  tileLayer: {
+    url: "https://tiles.example.com/{z}/{x}/{y}.png",
+    zoom: 2,
+    attribution: "Map data and imagery: Example Maps",
+    onError(error, tile) {
+      console.warn("Tile unavailable", tile, error);
+    },
+  },
+});
+```
+
+`url` accepts `{z}`, `{x}`, `{y}`, and `{-y}` placeholders. For private, signed, generated, or
+offline imagery, use `getTile({ x, y, z })` and return a URL, canvas, image, bitmap, or a Promise of
+one. Loaded XYZ coordinates are cached for the lifetime of the layer, and failed tiles leave the
+built-in CanvasGlobe background visible instead of breaking the render loop.
+
+This is an overview layer, not a slippy-map engine. `zoom` defaults to 2. The default `maxTiles: 64`
+allows up to zoom 3 and prevents a configuration mistake from starting hundreds of requests. Raise
+the ceiling explicitly only when the provider terms, page weight, and device budget allow it.
+
+Always supply the attribution required by your provider. CanvasGlobe paints it into the canvas, so
+it remains present in image and video exports. Remote images use anonymous CORS by default because
+globe reprojection and export must read their pixels. The provider must return a compatible
+`Access-Control-Allow-Origin` header. You may set `crossOrigin: null`, but a cross-origin response
+without CORS cannot be reprojected or exported. You are responsible for the provider's licence,
+usage policy, access token, and request limits.
+
 ### How accurate is marker placement?
 
 The projection maths is exact: a marker's pixel position matches the closed-form projection to

package/codemeta.json

@@ -3,9 +3,9 @@
   "@type": "SoftwareSourceCode",
   "name": "CanvasGlobe",
   "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.",
+  "description": "CanvasGlobe helps developers add interactive 3D globes and flat world maps to JavaScript and React apps with Canvas 2D, without WebGL, required map tiles, API keys, or required runtime network calls.",
   "url": "https://canvasglobe.swiftools.com/",
-  "version": "1.2.0",
+  "version": "1.4.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 }>" } }