canvas-globe 0.1.0

package/src/geo.js

@@ -0,0 +1,286 @@
+/**
+ * Pure geometry, projection and colour helpers. No DOM, no canvas: everything
+ * here is testable in isolation and safe to run in Node.
+ */
+
+export const D2R = Math.PI / 180;
+export const R2D = 180 / Math.PI;
+export const TAU = Math.PI * 2;
+
+export const clamp = (v, lo, hi) => (v < lo ? lo : v > hi ? hi : v);
+
+/** Wraps a longitude delta into -180…180. */
+export const wrapLon = (d) => {
+  let x = d;
+  while (x > 180) x -= 360;
+  while (x < -180) x += 360;
+  return x;
+};
+
+/* -------------------------------------------------------------------------- */
+/* map projections                                                            */
+/* -------------------------------------------------------------------------- */
+
+const MERCATOR_LIMIT = 85.0511287798;
+
+/**
+ * Each projection maps lon/lat to abstract planar units where +y points south,
+ * so a bounding box can be normalised to the canvas without special-casing.
+ */
+export const projections = {
+  equirectangular: {
+    forward: (lon, lat) => [lon, -lat],
+    inverse: (x, y) => [x, -y],
+  },
+  mercator: {
+    forward: (lon, lat) => {
+      const p = clamp(lat, -MERCATOR_LIMIT, MERCATOR_LIMIT) * D2R;
+      return [lon, -R2D * Math.log(Math.tan(Math.PI / 4 + p / 2))];
+    },
+    inverse: (x, y) => [x, R2D * (2 * Math.atan(Math.exp(-y * D2R)) - Math.PI / 2)],
+  },
+  naturalEarth: {
+    forward: (lon, lat) => {
+      const p = lat * D2R, l = lon * D2R, p2 = p * p, p4 = p2 * p2;
+      const x = l * (0.8707 - 0.131979 * p2 + p4 * (-0.013791 + p4 * (0.003971 * p2 - 0.001529 * p4)));
+      const y = p * (1.007226 + p2 * (0.015085 + p4 * (-0.044475 + 0.028874 * p2 - 0.005916 * p4)));
+      return [x * R2D, -y * R2D];
+    },
+    inverse: (x, y) => {
+      let p = -y * D2R;
+      for (let i = 0; i < 24; i++) {
+        const p2 = p * p, p4 = p2 * p2;
+        const f = p * (1.007226 + p2 * (0.015085 + p4 * (-0.044475 + 0.028874 * p2 - 0.005916 * p4))) + y * D2R;
+        const d = f / (1.007226 + p2 * (0.045255 + p4 * (-0.311325 + 0.259866 * p2 - 0.065076 * p4)));
+        p -= d;
+        if (Math.abs(d) < 1e-12) break;
+      }
+      const p2 = p * p, p4 = p2 * p2;
+      const k = 0.8707 - 0.131979 * p2 + p4 * (-0.013791 + p4 * (0.003971 * p2 - 0.001529 * p4));
+      return [(x * D2R) / k * R2D, p * R2D];
+    },
+  },
+};
+
+export const resolveProjection = (name) => projections[name] || projections.equirectangular;
+
+/** Planar bounds of a projection for a `[north, south]` latitude window. */
+export const projectionBounds = (name, latRange) => {
+  const p = resolveProjection(name);
+  const [north, south] = latRange;
+  const x0 = p.forward(-180, 0)[0], x1 = p.forward(180, 0)[0];
+  const y0 = p.forward(0, north)[1], y1 = p.forward(0, south)[1];
+  return { x0, x1, y0, y1, dx: x1 - x0, dy: y1 - y0 };
+};
+
+/** Height / width ratio a flat map should use for a latitude range. */
+export const mapAspect = (latRange = [83, -56], projection = "equirectangular") => {
+  const b = projectionBounds(projection, latRange);
+  return b.dy / b.dx;
+};
+
+/* -------------------------------------------------------------------------- */
+/* orthographic (globe)                                                       */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Orthographic forward projection. Returns `[x, y, cos]` in screen units with
+ * y pointing down; `cos < 0` means the point sits behind the globe.
+ */
+export const ortho = (lon, lat, lon0, lat0, r) => {
+  const l = (lon - lon0) * D2R, f = lat * D2R, f0 = lat0 * D2R;
+  const sf = Math.sin(f), cf = Math.cos(f), sf0 = Math.sin(f0), cf0 = Math.cos(f0), cl = Math.cos(l);
+  return [r * cf * Math.sin(l), -r * (cf0 * sf - sf0 * cf * cl), sf0 * sf + cf0 * cf * cl];
+};
+
+/** Inverse orthographic. Returns `[lon, lat]`, or null outside the disc. */
+export const orthoInverse = (x, y, lon0, lat0, r) => {
+  const rho = Math.hypot(x, y);
+  if (rho > r) return null;
+  const c = Math.asin(clamp(rho / r, -1, 1));
+  const sc = Math.sin(c), cc = Math.cos(c);
+  const f0 = lat0 * D2R, ym = -y;
+  if (rho < 1e-9) return [lon0, lat0];
+  const lat = Math.asin(clamp(cc * Math.sin(f0) + (ym * sc * Math.cos(f0)) / rho, -1, 1)) * R2D;
+  const lon = lon0 + Math.atan2(x * sc, rho * cc * Math.cos(f0) - ym * sc * Math.sin(f0)) * R2D;
+  return [wrapLon(lon), lat];
+};
+
+/* -------------------------------------------------------------------------- */
+/* great circles                                                              */
+/* -------------------------------------------------------------------------- */
+
+const toVec = (lon, lat) => {
+  const l = lon * D2R, f = lat * D2R, cf = Math.cos(f);
+  return [cf * Math.cos(l), cf * Math.sin(l), Math.sin(f)];
+};
+
+/** Angular distance between two coordinates, in degrees. */
+export const angularDistance = (lon1, lat1, lon2, lat2) => {
+  const a = toVec(lon1, lat1), b = toVec(lon2, lat2);
+  return Math.acos(clamp(a[0] * b[0] + a[1] * b[1] + a[2] * b[2], -1, 1)) * R2D;
+};
+
+/** Samples the shorter great-circle path between two coordinates. */
+export const greatCircle = (lon1, lat1, lon2, lat2, steps = 64) => {  const a = toVec(lon1, lat1), b = toVec(lon2, lat2);
+  const dot = clamp(a[0] * b[0] + a[1] * b[1] + a[2] * b[2], -1, 1);
+  const omega = Math.acos(dot);
+  const out = [];
+  if (omega < 1e-6) return [[lon1, lat1], [lon2, lat2]];
+  const so = Math.sin(omega);
+  for (let i = 0; i <= steps; i++) {
+    const t = i / steps;
+    const k1 = Math.sin((1 - t) * omega) / so, k2 = Math.sin(t * omega) / so;
+    const x = a[0] * k1 + b[0] * k2, y = a[1] * k1 + b[1] * k2, z = a[2] * k1 + b[2] * k2;
+    const h = Math.hypot(x, y);
+    out.push([Math.atan2(y, x) * R2D, Math.atan2(z, h) * R2D]);
+  }
+  return out;
+};
+
+/** Metres between two coordinates, on a spherical earth. */
+export const distanceMeters = (lon1, lat1, lon2, lat2) => angularDistance(lon1, lat1, lon2, lat2) * D2R * 6371008.8;
+
+/** Ring of points a fixed distance from a centre: a circle on the sphere. */
+export const circleAround = (lon, lat, meters, steps = 72) => {
+  const theta = clamp(meters / 6371008.8, 0, Math.PI * 0.85);
+  const f1 = lat * D2R, l1 = lon * D2R;
+  const sf1 = Math.sin(f1), cf1 = Math.cos(f1), st = Math.sin(theta), ct = Math.cos(theta);
+  const out = [];
+  for (let i = 0; i <= steps; i++) {
+    const b = (i / steps) * TAU;
+    const f2 = Math.asin(clamp(sf1 * ct + cf1 * st * Math.cos(b), -1, 1));
+    const l2 = l1 + Math.atan2(Math.sin(b) * st * cf1, ct - sf1 * Math.sin(f2));
+    out.push([wrapLon(l2 * R2D), f2 * R2D]);
+  }
+  return out;
+};
+
+/* -------------------------------------------------------------------------- */
+/* sun position                                                               */
+/* -------------------------------------------------------------------------- */
+
+/** Subsolar point (the coordinate where the sun is directly overhead). */
+export const subsolarPoint = (when = Date.now()) => {
+  const ms = when instanceof Date ? when.getTime() : Number(when);
+  const n = ms / 86400000 + 2440587.5 - 2451545.0;
+  const meanLon = (280.46 + 0.9856474 * n) * D2R;
+  const meanAnom = (357.528 + 0.9856003 * n) * D2R;
+  const ecl = meanLon + (1.915 * Math.sin(meanAnom) + 0.02 * Math.sin(2 * meanAnom)) * D2R;
+  const obl = (23.439 - 0.0000004 * n) * D2R;
+  const lat = Math.asin(Math.sin(obl) * Math.sin(ecl)) * R2D;
+  const ra = Math.atan2(Math.cos(obl) * Math.sin(ecl), Math.cos(ecl)) * R2D;
+  const gmst = ((18.697374558 + 24.06570982441908 * n) % 24 + 24) % 24;
+  return { lon: wrapLon(ra - gmst * 15), lat };
+};
+
+/* -------------------------------------------------------------------------- */
+/* polygon utilities                                                          */
+/* -------------------------------------------------------------------------- */
+
+const ringContains = (ring, lon, lat) => {
+  let inside = false;
+  for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
+    const xi = ring[i][0], yi = ring[i][1], xj = ring[j][0], yj = ring[j][1];
+    if (yi > lat !== yj > lat && lon < ((xj - xi) * (lat - yi)) / (yj - yi) + xi) inside = !inside;
+  }
+  return inside;
+};
+
+/** Ray-casting hit test against a GeoJSON Polygon or MultiPolygon. */
+export const pointInGeometry = (geom, lon, lat) => {
+  if (!geom) return false;
+  const polys = geom.type === "Polygon" ? [geom.coordinates] : geom.coordinates;
+  for (const poly of polys) {
+    if (!poly.length || !ringContains(poly[0], lon, lat)) continue;
+    let hole = false;
+    for (let i = 1; i < poly.length; i++) if (ringContains(poly[i], lon, lat)) { hole = true; break; }
+    if (!hole) return true;
+  }
+  return false;
+};
+
+/** `[west, south, east, north]` bounds of a Polygon or MultiPolygon. */
+export const geometryBounds = (geom) => {
+  let w = 180, s = 90, e = -180, n = -90;
+  const polys = geom.type === "Polygon" ? [geom.coordinates] : geom.coordinates;
+  for (const poly of polys) {
+    for (const ring of poly) {
+      for (const c of ring) {
+        if (c[0] < w) w = c[0];
+        if (c[0] > e) e = c[0];
+        if (c[1] < s) s = c[1];
+        if (c[1] > n) n = c[1];
+      }
+    }
+  }
+  return [w, s, e, n];
+};
+
+/* -------------------------------------------------------------------------- */
+/* shapes & colours                                                           */
+/* -------------------------------------------------------------------------- */
+
+/** Accepts GeoJSON of any flavour or the bundled `{ id, name, geometry }[]`. */
+export const normalizeShapes = (input) => {
+  if (!input) return null;
+  if (Array.isArray(input)) return input;
+  if (input.type === "FeatureCollection") {
+    return input.features.map((f) => ({
+      id: f.id,
+      name: f.properties?.name ?? f.properties?.NAME ?? f.properties?.ADMIN,
+      iso: f.properties?.iso ?? f.properties?.ISO_A2 ?? f.properties?.iso_a2,
+      geometry: f.geometry,
+    }));
+  }
+  if (input.type === "Feature") return [{ id: input.id, name: input.properties?.name, geometry: input.geometry }];
+  if (input.type) return [{ geometry: input }];
+  return null;
+};
+
+/** Converts `#rgb`/`#rrggbb` to `rgba()`; other formats pass through. */
+export const withAlpha = (color, a) => {
+  if (typeof color !== "string") return color;
+  if (color.startsWith("#") && (color.length === 7 || color.length === 4)) {
+    const hex = color.length === 4 ? color.replace(/#(.)(.)(.)/, "#$1$1$2$2$3$3") : color;
+    const n = parseInt(hex.slice(1), 16);
+    return `rgba(${(n >> 16) & 255},${(n >> 8) & 255},${n & 255},${a})`;
+  }
+  const m = color.match(/^rgba?\(([^)]+)\)$/i);
+  if (m) {
+    const p = m[1].split(",").map((s) => s.trim());
+    return `rgba(${p[0]},${p[1]},${p[2]},${a})`;
+  }
+  return color;
+};
+
+const parseRGB = (color) => {
+  if (color.startsWith("#")) {
+    const hex = color.length === 4 ? color.replace(/#(.)(.)(.)/, "#$1$1$2$2$3$3") : color;
+    const n = parseInt(hex.slice(1), 16);
+    return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+  }
+  const m = color.match(/^rgba?\(([^)]+)\)$/i);
+  if (m) return m[1].split(",").slice(0, 3).map((s) => parseFloat(s));
+  return [128, 128, 128];
+};
+
+/**
+ * Builds a linear colour ramp: `colorScale([0, 100], ["#eef", "#22c"])`.
+ * Domains longer than two entries create multi-stop scales.
+ */
+export const colorScale = (domain = [0, 1], range = ["#e0f2fe", "#0369a1"]) => {
+  const stops = range.map(parseRGB);
+  return (value) => {
+    const v = Number(value);
+    if (!Number.isFinite(v)) return null;
+    if (v <= domain[0]) return `rgb(${stops[0].join(",")})`;
+    const last = domain.length - 1;
+    if (v >= domain[last]) return `rgb(${stops[stops.length - 1].join(",")})`;
+    let i = 0;
+    while (i < last - 1 && v > domain[i + 1]) i++;
+    const t = (v - domain[i]) / (domain[i + 1] - domain[i] || 1);
+    const a = stops[Math.min(i, stops.length - 1)], b = stops[Math.min(i + 1, stops.length - 1)];
+    return `rgb(${Math.round(a[0] + (b[0] - a[0]) * t)},${Math.round(a[1] + (b[1] - a[1]) * t)},${Math.round(a[2] + (b[2] - a[2]) * t)})`;
+  };
+};

package/src/index.js

@@ -0,0 +1,19 @@
+export {
+  GeoGlobe,
+  GeoGlobe as CanvasGlobe,
+  createGlobe,
+  createGlobe as createCanvasGlobe,
+  world,
+} from "./geo-globe.js";
+export { themes, countryPalette } from "./themes.js";
+export { presets } from "./presets.js";
+export { scenes } from "./scenes.js";
+export { exportPresets, exportSize } from "./export.js";
+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 { Media, drawFitted } from "./media.js";
+export { DEFAULT_LICENSE_KEY, inspectLicenseKey, hasLicenseKey } from "./license.js";
+export { mapAspect, colorScale, subsolarPoint, greatCircle, angularDistance, pointInGeometry, geometryBounds, projections } from "./geo.js";
+export { default } from "./geo-globe.js";

package/src/license.js

@@ -0,0 +1,36 @@
+/** License-key configuration helpers. */
+export const DEFAULT_LICENSE_KEY = "0000-0000-000-0000";
+
+/** Returns the configured license-key status. */
+export function inspectLicenseKey(value) {
+  const key = typeof value === "string" ? value : "";
+  if (!key) return { valid: false, kind: "missing", key: "" };
+  if (key === DEFAULT_LICENSE_KEY) {
+    return { valid: false, kind: "placeholder", key };
+  }
+  return { valid: true, kind: "provided", key };
+}
+
+/** Returns whether a configured license key is available. */
+export function hasLicenseKey(value) {
+  return inspectLicenseKey(value).valid;
+}
+
+/** Reports missing or placeholder keys in the browser console. */
+export function reportLicenseStatus(value) {
+  const status = inspectLicenseKey(value);
+  // CanvasGlobe can be constructed in non-browser test and rendering
+  // environments. Console messaging applies when it is used in a browser.
+  if (typeof location === "undefined") return status;
+  if (status.kind === "missing") {
+    console.error(
+      "canvas-globe: please provide a valid license key. For help, email globe@swiftools.com",
+    );
+  } else if (status.kind === "placeholder") {
+    console.warn(
+      `canvas-globe: ${DEFAULT_LICENSE_KEY} license key is not valid for production use. ` +
+        "For help, email globe@swiftools.com",
+    );
+  }
+  return status;
+}

package/src/media.js

@@ -0,0 +1,160 @@
+/**
+ * Media sources that can be painted inside a country's outline: a still, an
+ * animated GIF, a video, another canvas, or a live MediaStream.
+ *
+ * Everything is drawn with `drawImage`, so the only real work is keeping a
+ * drawable element alive and knowing whether it needs a redraw each frame.
+ */
+
+const VIDEO_RE = /\.(mp4|webm|ogv|mov|m4v)(\?|#|$)/i;
+const GIF_RE = /\.gif(\?|#|$)/i;
+
+const isDrawable = (v) =>
+  !!v && typeof v === "object" &&
+  (v.nodeName === "IMG" || v.nodeName === "VIDEO" || v.nodeName === "CANVAS" ||
+    (typeof ImageBitmap !== "undefined" && v instanceof ImageBitmap) ||
+    (typeof OffscreenCanvas !== "undefined" && v instanceof OffscreenCanvas));
+
+const isStream = (v) => typeof MediaStream !== "undefined" && v instanceof MediaStream;
+
+/** Keeps GIFs advancing: browsers only animate images attached to the document. */
+const parkOffscreen = (el) => {
+  if (typeof document === "undefined") return;
+  el.style.cssText = "position:fixed;right:0;bottom:0;width:1px;height:1px;opacity:.01;pointer-events:none;z-index:-1";
+  document.body.appendChild(el);
+};
+
+export class Media {
+  constructor(spec, onReady) {
+    const config = spec && typeof spec === "object" && "src" in spec && !isDrawable(spec) ? spec : { src: spec };
+    this.fit = config.fit || "cover";
+    this.opacity = config.opacity ?? 1;
+    this.blend = config.blend || null;
+    this.scale = config.scale ?? 1;
+    this.offset = config.offset || [0, 0];
+    this.ready = false;
+    this.error = null;
+    this._owned = false;
+    this._onReady = onReady;
+    this._load(config);
+  }
+
+  _load(config) {
+    const src = config.src;
+    if (isDrawable(src)) {
+      this.element = src;
+      this.ready = true;
+      this._kind = src.nodeName === "VIDEO" ? "video" : "static";
+      return;
+    }
+    if (isStream(src)) {
+      this.element = this._video(config);
+      if (this.element) this.element.srcObject = src;
+      this._kind = "video";
+      return;
+    }
+    if (typeof src !== "string") {
+      this.error = new Error("canvas-globe: unsupported media source");
+      return;
+    }
+    if (config.type === "video" || (config.type !== "image" && VIDEO_RE.test(src))) {
+      this.element = this._video(config);
+      if (this.element) this.element.src = src;
+      this._kind = "video";
+      return;
+    }
+    if (typeof Image === "undefined") return;
+    const img = new Image();
+    img.crossOrigin = config.crossOrigin ?? "anonymous";
+    img.onload = () => {
+      this.ready = true;
+      this._onReady?.(this);
+    };
+    img.onerror = () => {
+      this.error = new Error(`canvas-globe: could not load "${src}"`);
+      this._onReady?.(this);
+    };
+    img.src = src;
+    this.element = img;
+    this._owned = true;
+    this._kind = GIF_RE.test(src) ? "gif" : "static";
+    if (this._kind === "gif") parkOffscreen(img);
+  }
+
+  _video(config) {
+    if (typeof document === "undefined") {
+      this.error = new Error("canvas-globe: video media needs a DOM");
+      return null;
+    }
+    const el = document.createElement("video");
+    el.muted = config.muted !== false;
+    el.loop = config.loop !== false;
+    el.autoplay = true;
+    el.playsInline = true;
+    el.crossOrigin = config.crossOrigin ?? "anonymous";
+    el.oncanplay = () => {
+      this.ready = true;
+      this._onReady?.(this);
+    };
+    el.onerror = () => {
+      this.error = new Error("canvas-globe: video could not be played");
+      this._onReady?.(this);
+    };
+    this._owned = true;
+    parkOffscreen(el);
+    el.play?.().catch(() => {});
+    return el;
+  }
+
+  /** Natural pixel size of the current frame. */
+  size() {
+    const el = this.element;
+    if (!el) return null;
+    const w = el.videoWidth || el.naturalWidth || el.width;
+    const h = el.videoHeight || el.naturalHeight || el.height;
+    return w && h ? [w, h] : null;
+  }
+
+  /** True when the source changes on its own and needs a redraw every frame. */
+  get animated() {
+    if (!this.element) return false;
+    if (this._kind === "gif") return true;
+    return this._kind === "video" && !this.element.paused && !this.element.ended;
+  }
+
+  destroy() {
+    if (!this._owned || !this.element) return;
+    if (this._kind === "video") {
+      this.element.pause?.();
+      this.element.srcObject = null;
+      this.element.removeAttribute("src");
+    }
+    this.element.remove?.();
+    this.element = null;
+    this.ready = false;
+  }
+}
+
+/**
+ * Draws media into a screen rect the way CSS `object-fit` would.
+ * The caller is expected to have clipped to the target shape already.
+ */
+export function drawFitted(ctx, media, box) {
+  const size = media.size();
+  if (!size) return false;
+  const [mw, mh] = size;
+  const [x, y, w, h] = box;
+  if (w <= 0 || h <= 0) return false;
+  let scale;
+  if (media.fit === "contain") scale = Math.min(w / mw, h / mh);
+  else if (media.fit === "fill") scale = null;
+  else scale = Math.max(w / mw, h / mh);
+  const k = media.scale || 1;
+  if (scale === null) {
+    ctx.drawImage(media.element, x, y, w, h);
+    return true;
+  }
+  const dw = mw * scale * k, dh = mh * scale * k;
+  ctx.drawImage(media.element, x + (w - dw) / 2 + media.offset[0], y + (h - dh) / 2 + media.offset[1], dw, dh);
+  return true;
+}

package/src/presets.js

@@ -0,0 +1,21 @@
+/**
+ * Named bundles of theme + render style. `createGlobe(canvas, { preset })`
+ * applies one, and your own options still win over anything it sets.
+ */
+export const presets = {
+  atlas: { theme: "atlas", landStyle: "fill", graticule: true, stars: true, shade: true, orbits: 0 },
+  midnight: { theme: "midnight", landStyle: "fill", graticule: true, stars: true, shade: true, orbits: 0 },
+  mono: { theme: "mono", landStyle: "fill", graticule: true, stars: false, shade: false, orbits: 0 },
+  political: { theme: "political", landStyle: "fill", countryColors: "auto", graticule: true, stars: false, shade: true, orbits: 0 },
+  hologram: { theme: "hologram", landStyle: "dots", dotSpacing: 2, dotSize: 1.15, graticule: true, stars: true, shade: false, orbits: 0 },
+  neon: { theme: "neon", landStyle: "glow", graticule: true, stars: true, shade: false, orbits: 0 },
+  blueprint: { theme: "blueprint", landStyle: "outline", graticule: true, stars: false, shade: false, orbits: 3 },
+  aurora: { theme: "aurora", landStyle: "dots", dotSpacing: 2.6, dotSize: 1.4, graticule: false, stars: true, shade: false, orbits: 2 },
+  noir: { theme: "noir", landStyle: "outline", graticule: false, stars: false, shade: false, orbits: 0 },
+  constellation: { theme: "hologram", landStyle: "dots", dotSpacing: 3, dotSize: 1.6, graticule: true, stars: true, shade: false, orbits: 3 },
+};
+
+/** Option keys a preset owns; anything unset falls back to the default. */
+export const presetKeys = [
+  "theme", "landStyle", "dotSpacing", "dotSize", "graticule", "stars", "shade", "orbits", "countryColors",
+];

package/src/react.js

@@ -0,0 +1,60 @@
+/**
+ * React binding. `import { Globe } from "canvas-globe/react"`.
+ * React is a peer dependency and is only required by this entry point.
+ */
+import { createElement, forwardRef, useEffect, useImperativeHandle, useRef } from "react";
+import { GeoGlobe } from "./geo-globe.js";
+import { mapAspect } from "./geo.js";
+
+const CALLBACKS = ["onHover", "onClick", "onCountryHover", "onCountryClick", "onRender"];
+
+export const Globe = forwardRef(function Globe(props, ref) {
+  const { className, style, ...rest } = props;
+  const options = {};
+  for (const key of Object.keys(rest)) if (!CALLBACKS.includes(key)) options[key] = rest[key];
+
+  const canvasRef = useRef(null);
+  const globeRef = useRef(null);
+  const handlers = useRef(props);
+  const previous = useRef(null);
+  const initial = useRef(options);
+  handlers.current = props;
+
+  useEffect(() => {
+    const bound = {};
+    for (const name of CALLBACKS) bound[name] = (...args) => handlers.current[name]?.(...args);
+    const globe = new GeoGlobe(canvasRef.current, { ...initial.current, ...bound });
+    globeRef.current = globe;
+    previous.current = initial.current;
+    return () => {
+      globe.destroy();
+      globeRef.current = null;
+    };
+  }, []);
+
+  // Shallow diff every render so callers can pass inline objects freely.
+  useEffect(() => {
+    const globe = globeRef.current;
+    if (!globe) return;
+    const patch = {};
+    let changed = false;
+    for (const key of Object.keys(options)) {
+      if (previous.current && previous.current[key] === options[key]) continue;
+      patch[key] = options[key];
+      changed = true;
+    }
+    previous.current = options;
+    if (changed) globe.setOptions(patch);
+  });
+
+  useImperativeHandle(ref, () => globeRef.current);
+
+  const aspect = options.mode === "map" ? 1 / mapAspect(options.latRange, options.projection) : 1;
+  return createElement("canvas", {
+    ref: canvasRef,
+    className,
+    style: { width: "100%", aspectRatio: String(aspect), ...style },
+  });
+});
+
+export default Globe;

package/src/recorder.js

@@ -0,0 +1,70 @@
+/**
+ * Canvas → WebM recording via MediaRecorder. No encoder dependency, no upload,
+ * no server: the clip is produced entirely in the tab.
+ */
+
+const CANDIDATES = [
+  "video/webm;codecs=vp9",
+  "video/webm;codecs=vp8",
+  "video/webm",
+  "video/mp4",
+];
+
+/** First container the browser can actually encode, or null. */
+export function supportedRecordingType() {
+  if (typeof MediaRecorder === "undefined") return null;
+  for (const type of CANDIDATES) if (MediaRecorder.isTypeSupported?.(type)) return type;
+  return null;
+}
+
+export const canRecord = () => supportedRecordingType() !== null;
+
+/**
+ * Records the canvas and resolves to a Blob. Pass `duration` for a fixed-length
+ * clip, or call `stop()` on the returned handle.
+ */
+export function recordCanvas(canvas, { duration = 6000, fps = 30, bitrate = 6e6, type } = {}) {
+  const mimeType = type || supportedRecordingType();
+  if (!mimeType) return { promise: Promise.reject(new Error("canvas-globe: MediaRecorder is unavailable")), stop() {} };
+  if (!canvas.captureStream) {
+    return { promise: Promise.reject(new Error("canvas-globe: canvas.captureStream is unavailable")), stop() {} };
+  }
+
+  const stream = canvas.captureStream(fps);
+  const recorder = new MediaRecorder(stream, { mimeType, videoBitsPerSecond: bitrate });
+  const chunks = [];
+  let timer = null;
+
+  const promise = new Promise((resolve, reject) => {
+    recorder.ondataavailable = (e) => {
+      if (e.data && e.data.size) chunks.push(e.data);
+    };
+    recorder.onerror = (e) => reject(e.error || new Error("canvas-globe: recording failed"));
+    recorder.onstop = () => {
+      clearTimeout(timer);
+      for (const track of stream.getTracks()) track.stop();
+      resolve(new Blob(chunks, { type: mimeType }));
+    };
+    recorder.start();
+    if (duration > 0) timer = setTimeout(() => recorder.state !== "inactive" && recorder.stop(), duration);
+  });
+
+  return {
+    promise,
+    mimeType,
+    stop() {
+      if (recorder.state !== "inactive") recorder.stop();
+      return promise;
+    },
+  };
+}
+
+/** Triggers a browser download for a Blob. */
+export function downloadBlob(blob, filename) {
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  a.click();
+  setTimeout(() => URL.revokeObjectURL(url), 1000);
+}