canvas-globe 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -6,6 +6,36 @@ All notable changes to this package are documented here. The format follows
 
 ## [Unreleased]
 
+## [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
+  the official CanvasGlobe website and its Cloudflare preview deployments.
+- Kept the licensing presentation unchanged for customer production domains.
+
 ## [1.1.0] - 2026-09-17
 
 - Added official Vue, Angular, Svelte, and Web Component packages that keep

package/README.md

@@ -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.0/dist/canvas-globe.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/canvas-globe@1.2.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.0/dist/canvas-globe.umd.js"></script>
+<script src="https://unpkg.com/canvas-globe@1.2.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.0";
+import { createGlobe } from "https://esm.sh/canvas-globe@1.2.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.0/dist/canvas-globe.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/canvas-globe@1.2.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 |

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.0",
+  "version": "1.2.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/dist/canvas-globe.umd.js

@@ -1314,7 +1314,7 @@ function drawFitted(ctx, media, box) {
 }
 
 // Keep in sync with package.json. Release checks enforce this value.
-const CANVAS_GLOBE_VERSION = "1.1.0";
+const CANVAS_GLOBE_VERSION = "1.2.0";
 
 /** Local license-key checks and production-use presentation helpers. */
 
@@ -1342,9 +1342,18 @@ const PRIVATE_HOST_PATTERNS = [
   /^::1$/,
 ];
 
+const OFFICIAL_SITE_HOSTS = new Set([
+  "canvasglobe.swiftools.com",
+  "canvas-globe-website.pages.dev",
+]);
+const OFFICIAL_PREVIEW_SUFFIX = ".canvas-globe-website.pages.dev";
+
 const normalizeLicenseKey = (value) =>
   typeof value === "string" ? value.trim() : "";
 
+const isOfficialSiteHost = (hostname) =>
+  OFFICIAL_SITE_HOSTS.has(hostname) || hostname.endsWith(OFFICIAL_PREVIEW_SUFFIX);
+
 /** Returns development, production or unknown for a browser location. */
 function inspectRuntime(locationValue = globalThis.location) {
   if (!locationValue) return { kind: "unknown", hostname: "", public: false };
@@ -1391,7 +1400,7 @@ function getLicensePresentation(
 ) {
   const status = inspectLicenseKey(value, mode);
   const runtime = inspectRuntime(locationValue);
-  if (!mode || status.valid || !runtime.public) {
+  if (!mode || status.valid || !runtime.public || isOfficialSiteHost(runtime.hostname)) {
     return { status, runtime, notice: null };
   }
   return {
@@ -1411,6 +1420,7 @@ function reportLicenseStatus(value, mode = COMMERCIAL_LICENSE_MODE) {
   const presentation = getLicensePresentation(value, globalThis.location, mode);
   const { status } = presentation;
   if (typeof location === "undefined") return status;
+  if (!presentation.notice) return status;
   if (status.kind === "missing") {
     console.error(
       mode
@@ -1510,10 +1520,24 @@ const DEFAULTS = {
   onCountryHover: null,
   onCountryClick: null,
   onRender: null,
+  effects: null,
 };
 
 const coord = (v) => (Array.isArray(v) ? [v[0], v[1]] : [v.lon ?? v.lng ?? v.longitude, v.lat ?? v.latitude]);
 
+const now = () => (typeof performance !== "undefined" ? performance.now() : Date.now());
+
+/**
+ * An effect's own 0→1 progress at a point on the shared clock. Derived purely
+ * from `ms`, so the same millisecond always renders the same frame.
+ */
+const phaseOf = (fx, ms) => {
+  const duration = Math.max(1, fx.duration ?? 1000);
+  const total = duration + (fx.hold ?? 0);
+  const elapsed = fx.loop === false ? Math.min(ms, total) : ((ms % total) + total) % total;
+  return Math.min(1, elapsed / duration);
+};
+
 const defaultTooltip = (target, kind) => {
   if (kind === "country") return target.name || String(target.id ?? "");
   if (kind === "cluster") return `${target.count} in this area`;
@@ -1568,6 +1592,11 @@ class GeoGlobe {
     this._licenseHits = [];
     this._licenseDismissed = false;
     this._licenseHovered = false;
+    this._fx = [];
+    this._clock = null;
+    this._t0 = now();
+    this._spinBase = this.lon;
+    this.pointer = { x: 0, y: 0, lon: 0, lat: 0, over: false };
 
     this._applyWorld();
     this._applyMarkers(this.o.markers);
@@ -1579,12 +1608,138 @@ class GeoGlobe {
     this.resize();
     if (this.o.focus) this.focusOn(this.o.focus, { instant: true });
     if (this.o.showViewer) this._initViewer();
+    for (const fx of this.o.effects || []) this.use(fx);
     this._loop = this._loop.bind(this);
     this._raf = requestAnimationFrame(this._loop);
   }
 
   /* ------------------------------ public API ------------------------------ */
 
+  /* --------------------------------- effects ------------------------------- */
+
+  /** Installs an effect. Returns `this`, so calls chain. */
+  use(effect) {
+    if (!effect || typeof effect.frame !== "function") return this;
+    this._fx.push({ fx: effect, state: effect.setup?.(this) ?? {} });
+    this._fx.sort((a, b) => (a.fx.z ?? 0) - (b.fx.z ?? 0));
+    return this.invalidate();
+  }
+
+  /** Removes an effect by reference or by name. */
+  remove(effect) {
+    const i = this._fx.findIndex((e) => e.fx === effect || e.fx.name === effect);
+    if (i < 0) return this;
+    const [entry] = this._fx.splice(i, 1);
+    entry.fx.dispose?.(entry.state, this);
+    return this.invalidate();
+  }
+
+  clearEffects() {
+    while (this._fx.length) this.remove(this._fx[0].fx);
+    return this;
+  }
+
+  get effects() {
+    return this._fx.map((e) => e.fx);
+  }
+
+  /**
+   * Pins the effect clock to `ms`. Rendering becomes reproducible, which is
+   * what frame-exact export and seamless loops need. `play()` releases it.
+   */
+  seek(ms) {
+    // Capture where auto-rotation started from, so longitude can be derived
+    // from the clock instead of accumulated per frame. Only on the way in:
+    // seeking again while already seeked must not shift the origin.
+    if (this._clock == null) this._spinBase = wrapLon(this.lon - this._spinRate() * this._fxTime());
+    this._clock = Math.max(0, ms);
+    if (this._autoSpin()) this.lon = wrapLon(this._spinBase + this._spinRate() * this._clock);
+    return this.invalidate();
+  }
+
+  play() {
+    // Resume the timeline where it was paused rather than snapping back to 0.
+    if (this._clock != null) this._t0 = now() - this._clock;
+    this._clock = null;
+    return this.invalidate();
+  }
+
+  /** Draws the single frame that belongs at `ms` on the effect clock. */
+  renderFrame(ms) {
+    return this.seek(ms).render();
+  }
+
+  _fxTime() {
+    return this._clock != null ? this._clock : now() - this._t0;
+  }
+
+  /**
+   * Wall clock for looping scene animation. Pinned while seeking, so arcs,
+   * orbits and pulses land on the same phase every time a frame is redrawn.
+   */
+  _animTime() {
+    return this._clock != null ? this._clock : Date.now();
+  }
+
+  /** Degrees of auto-rotation per millisecond. */
+  _spinRate() {
+    return ((this.o.rotateSpeed || 0) * (this.o.fps || 30)) / 1000;
+  }
+
+  _runPasses(stage) {
+    if (!this._fx.length) return;
+    const ms = this._fxTime();
+    const { ctx } = this;
+    for (const entry of this._fx) {
+      if ((entry.fx.stage || "above") !== stage) continue;
+      ctx.save();
+      try {
+        entry.fx.frame(ctx, this, phaseOf(entry.fx, ms), entry.state);
+      } catch (err) {
+        // One bad effect must not take the render loop down with it.
+        if (!entry.failed) {
+          entry.failed = true;
+          console.error(`canvas-globe: effect "${entry.fx.name || "anonymous"}" failed`, err);
+        }
+      }
+      ctx.restore();
+    }
+  }
+
+  /** Land sample points as `[lon, lat]` pairs — what the dot matrix draws. */
+  landPoints(spacing) {
+    const prev = this.o.dotSpacing;
+    if (spacing != null) this.o.dotSpacing = spacing;
+    const flat = this._dotPoints();
+    this.o.dotSpacing = prev;
+    const out = [];
+    for (let i = 0; i < flat.length; i += 2) out.push([flat[i], flat[i + 1]]);
+    return out;
+  }
+
+  /** Traces a country outline into a path using the current projection. */
+  tracePath(shape, ctx = this.ctx, transform) {
+    const geom = shape?.geometry || shape;
+    if (!geom?.coordinates) return this;
+    const polys = geom.type === "Polygon" ? [geom.coordinates] : geom.coordinates;
+    for (const poly of polys) {
+      for (const ring of poly) {
+        let open = false;
+        for (const c of ring) {
+          const src = transform ? transform(c) : c;
+          const p = this.project(src[0], src[1]);
+          if (!p) {
+            open = false;
+            continue;
+          }
+          open ? ctx.lineTo(p.x, p.y) : (ctx.moveTo(p.x, p.y), (open = true));
+        }
+        if (open) ctx.closePath();
+      }
+    }
+    return this;
+  }
+
   setMarkers(markers = []) {
     this._applyMarkers(markers);
     this._focus = -1;
@@ -2141,9 +2296,12 @@ class GeoGlobe {
     const { w, h } = this._size();
     ctx.setTransform(this._dpr, 0, 0, this._dpr, 0, 0);
     ctx.clearRect(0, 0, w, h);
+    this._runPasses("beneath");
     this.hits = this.o.mode === "map" ? this._paintMap(w, h) : this._paintGlobe(w, h);
     this._dirty = false;
+    this._runPasses("above");
     this.o.onRender?.(this);
+    this._runPasses("post");
     this._paintLicenseNotice(w, h);
     return this;
   }
@@ -2161,6 +2319,7 @@ class GeoGlobe {
   destroy() {
     this._destroyed = true;
     cancelAnimationFrame(this._raf);
+    this.clearEffects();
     this.stopTour();
     this.stopStory();
     this.stopTimeline();
@@ -2615,6 +2774,15 @@ class GeoGlobe {
     this._onMove = (e) => {
       const [x, y] = this._local(e);
       this._pointer = { x: e.clientX, y: e.clientY };
+      this.pointer.x = x;
+      this.pointer.y = y;
+      this.pointer.over = true;
+      const at = this.unproject(x, y);
+      if (at) {
+        this.pointer.lon = at[0];
+        this.pointer.lat = at[1];
+      }
+      if (this._fx.length) this._dirty = true;
       const licenseHovered = this._licenseHitAt(x, y);
       if (licenseHovered !== this._licenseHovered) {
         this._licenseHovered = licenseHovered;
@@ -2685,6 +2853,7 @@ class GeoGlobe {
     this._onLeave = (e) => {
       this._onUp(e);
       this._pointer = null;
+      this.pointer.over = false;
       this._licenseHovered = false;
       if (this._hovered || this._hoveredCountry) {
         if (this._hovered) this.o.onHover?.(null, null);
@@ -2865,13 +3034,20 @@ class GeoGlobe {
 
   /* --------------------------------- loop --------------------------------- */
 
-  _spinning() {
+  /** Auto-rotation is configured and permitted, regardless of the clock. */
+  _autoSpin() {
     return !!this.o.autoRotate && !this._reducedMotion() && !this._drag && !this._vel && this.o.mode === "globe";
   }
 
+  /** Auto-rotation should advance on its own this frame. */
+  _spinning() {
+    return this._autoSpin() && this._clock == null;
+  }
+
   /** True while something on screen still needs to move. */
   _animating() {
     if (this._target || this._drag || this._vel) return true;
+    if (this._fx.length && this._clock == null) return true;
     if (this._spinning()) return true;
     if (this._reducedMotion()) return false;
     if (this._hasLive || this._pings.length) return true;
@@ -3145,7 +3321,7 @@ class GeoGlobe {
     const list = this._orbitList();
     if (!list.length) return;
     const { ctx } = this;
-    const spin = this._reducedMotion() ? 0 : (Date.now() / 1000) % 3600;
+    const spin = this._reducedMotion() ? 0 : (this._animTime() / 1000) % 3600;
     ctx.lineCap = "round";
     for (const orbit of list) {
       const inc = (orbit.inclination ?? 30) * D2R;
@@ -3699,7 +3875,7 @@ class GeoGlobe {
     const arcs = this.o.arcs;
     if (!arcs || !arcs.length) return;
     const { ctx } = this;
-    const now = Date.now();
+    const now = this._animTime();
     const still = this._reducedMotion();
     ctx.lineCap = "round";
     ctx.lineJoin = "round";
@@ -4428,7 +4604,7 @@ class GeoGlobe {
     }
 
     if (m.live && !this._reducedMotion()) {
-      const pulse = (Date.now() % 2200) / 2200;
+      const pulse = (this._animTime() % 2200) / 2200;
       ctx.globalAlpha = 1 - pulse;
       ctx.strokeStyle = t.live;
       ctx.lineWidth = 1.4 * scale;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canvas-globe",
-  "version": "1.1.0",
+  "version": "1.2.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": {
@@ -66,6 +66,36 @@
       "import": "./src/react.js",
       "default": "./src/react.js"
     },
+    "./fx": {
+      "types": "./types/fx.d.ts",
+      "import": "./src/fx/index.js",
+      "default": "./src/fx/index.js"
+    },
+    "./fx/interaction": {
+      "types": "./types/fx-interaction.d.ts",
+      "import": "./src/fx/effects/interaction.js",
+      "default": "./src/fx/effects/interaction.js"
+    },
+    "./recipes": {
+      "types": "./types/recipes.d.ts",
+      "import": "./src/recipes.js",
+      "default": "./src/recipes.js"
+    },
+    "./charts": {
+      "types": "./types/charts.d.ts",
+      "import": "./src/charts.js",
+      "default": "./src/charts.js"
+    },
+    "./controls": {
+      "types": "./types/controls.d.ts",
+      "import": "./src/controls.js",
+      "default": "./src/controls.js"
+    },
+    "./places": {
+      "types": "./types/places.d.ts",
+      "import": "./src/places.js",
+      "default": "./src/places.js"
+    },
     "./data/world": {
       "types": "./types/data/world.d.ts",
       "import": "./src/data/world.js",
@@ -95,7 +125,9 @@
   "scripts": {
     "start": "node scripts/serve.mjs",
     "build": "node scripts/build.mjs",
-    "data": "node scripts/generate-data.mjs && node scripts/generate-timezones.mjs",
+    "data": "node scripts/generate-data.mjs && node scripts/generate-timezones.mjs && node scripts/generate-places.mjs",
+    "places": "node scripts/generate-places.mjs",
+    "audit:docs": "node scripts/audit-docs.mjs",
     "example": "node scripts/serve.mjs",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",