canvas-globe 1.1.1 → 1.3.0

package/CHANGELOG.md

@@ -6,6 +6,50 @@ 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
+
+- Added an opt-in effect system with 54 composable effects, three paint stages,
+  deterministic timeline controls, pointer state, path tracing, and land-point
+  sampling through `canvas-globe/fx`.
+- Added nine chart layers in `canvas-globe/charts`, six reversible recipes in
+  `canvas-globe/recipes`, and four markup-independent DOM controls in
+  `canvas-globe/controls`.
+- Added `canvas-globe/places`, an optional offline search module containing
+  6,772 populated places from Natural Earth.
+- Added 26 effect-authoring helpers for easing, deterministic particles,
+  scratch buffers, spherical geometry, HUD elements, and pointer interaction.
+- Added five effect and interaction demo pages plus export, type, package, and
+  documentation coverage for all new public entry points.
+
+### Changed
+
+- Made auto-rotation, arcs, orbits, and marker pulses follow the seekable clock
+  during frame rendering.
+- Kept all add-on modules outside the core entry point, leaving the core bundle
+  at 125.0 KB gzipped.
+
 ## [1.1.1] - 2026-09-17
 
 - Prevented the production licensing presentation from covering live globes on

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`
 
@@ -56,6 +56,10 @@ key, tile service, or runtime network request.
 - **Viewer location:** estimate a region from the browser time zone without a permission prompt
 - **Live pings:** display recent activity without requiring a CanvasGlobe backend
 - **Recording:** export a WebM clip in the browser
+- **Optional effects:** 54 seekable visual and interaction effects in `canvas-globe/fx`
+- **Chart layers:** nine animated geographic chart treatments in `canvas-globe/charts`
+- **Recipes and controls:** complete looks and DOM bindings without adding framework code
+- **Place search:** an optional 6,772-place search table with no runtime API request
 - **Presets:** ten included visual styles
 - **Day and night:** calculate the solar terminator for a given time
 - **Four projections:** orthographic, equirectangular, Mercator, and Natural Earth
@@ -135,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.1.1/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.1.1/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.1.1";
+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.
@@ -167,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.1.1/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"), {
@@ -284,6 +288,74 @@ npx skills add https://github.com/Shree-hari/canvas-globe --skill canvas-globe
 
 Or copy the maintained prompt from the [AI-assisted setup guide](https://canvasglobe.swiftools.com/getting-started/ai-assisted-setup). The skill and prompt select the correct framework entry point, include cleanup and accessibility, and require the user to purchase a production license before shipping.
 
+## Effects, charts, recipes, controls, and place search
+
+The animation and data-visualization modules are separate entry points. The
+core globe remains about 125 KB gzipped, and applications only download the
+modules they import.
+
+| Import | Approximate gzip size | Includes |
+| --- | ---: | --- |
+| `canvas-globe/fx` | 25.4 KB | 54 visual, transition, data, camera, and interaction effects plus authoring helpers |
+| `canvas-globe/charts` | 4.3 KB | Nine animated chart layers |
+| `canvas-globe/recipes` | 2.0 KB | Six complete, reversible compositions |
+| `canvas-globe/controls` | 1.8 KB | Search, timeline, threshold, and crossfilter bindings |
+| `canvas-globe/places` | 93.6 KB | Search over 6,772 bundled places |
+
+Effects are plain objects installed on a globe. They can be combined, removed,
+and rendered at an exact timeline position:
+
+```js
+import { createGlobe } from "canvas-globe";
+import { aurora, counterRoll, routeDashes } from "canvas-globe/fx";
+import { tilegram } from "canvas-globe/charts";
+
+const globe = createGlobe(canvas, { preset: "midnight", markers });
+globe
+  .use(aurora())
+  .use(routeDashes({ routes }))
+  .use(counterRoll({ to: 21947, caption: "customers", position: "bottom-center" }));
+
+globe.renderFrame(1200); // draw the frame at 1.2 seconds
+globe.use(tilegram({ values: countryValues }));
+```
+
+Use a recipe when you want a complete look rather than individual effects:
+
+```js
+import { applyRecipe, keynoteGlobe } from "canvas-globe/recipes";
+
+const undo = applyRecipe(globe, keynoteGlobe({ countries: 68 }));
+undo(); // restores the previous options and removes the recipe effects
+```
+
+Controls bind elements you already own and return cleanup functions. They do
+not inject markup or styles:
+
+```js
+import { searchAndFly } from "canvas-globe/controls";
+import { placeSource } from "canvas-globe/places";
+
+const unbind = searchAndFly(globe, document.querySelector("#place-search"), {
+  source: placeSource(),
+});
+```
+
+`canvas-globe/places` is optional because its city table is almost as large as
+the country geometry. Core already resolves countries and roughly 300 major
+cities. Import the place module only when broader offline city search is worth
+the extra payload.
+
+`seek(ms)` and `renderFrame(ms)` pin the effect clock, auto-rotation, arcs,
+orbits, and marker pulses. `windField` and part of
+`glitch` accumulate the previous frame by design, so reproduce them by
+exporting frames sequentially. Live media, newly fired pings, and a terminator
+using the current time are external dynamic state and should be fixed or
+disabled for frame-exact export.
+
+Custom effects use the same public contract and authoring helpers as the
+included effects. See `types/fx.d.ts` for every option and callback signature.
+
 ## Options
 
 | Option | Default | Description |
@@ -309,6 +381,7 @@ Or copy the maintained prompt from the [AI-assisted setup guide](https://canvasg
 | `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 }` |
@@ -371,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/THIRD_PARTY_NOTICES.md

@@ -5,6 +5,7 @@ CanvasGlobe includes geographic data derived from these sources:
 | Files | Source | Terms |
 | --- | --- | --- |
 | `src/data/world.js` | [Natural Earth 1:110m](https://www.naturalearthdata.com/about/terms-of-use/) through [world-atlas](https://github.com/topojson/world-atlas) | Natural Earth states that its data is public domain |
+| `src/data/places.js` | [Natural Earth 1:10m populated places](https://www.naturalearthdata.com/downloads/10m-cultural-vectors/10m-populated-places/) | Natural Earth states that its data is public domain |
 | `src/data/india.js` | [Datameet india-composite](https://github.com/datameet/maps) | CC0 / public-domain dedication as stated by the source repository |
 
 The CanvasGlobe Software License Agreement applies to CanvasGlobe's original software

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.1.1",
+  "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 }>" } }