canvas-globe 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -6,6 +6,25 @@ All notable changes to this package are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.1.5] - 2026-09-15
+
+- Added an animated README demo, Storybook stories, framework starters, a
+  shadcn registry component, Context7 metadata, and a reusable coding-agent
+  skill.
+- Added publishable `react-canvas-globe` and `create-canvas-globe` companion
+  packages for package-name discovery and project scaffolding.
+- Fixed React client-component compatibility and forwarded-ref lifecycle
+  updates, plus safe cleanup for asynchronously loaded Svelte integrations.
+- Improved README capture portability and pinned the Chromatic workflow action
+  to an immutable release commit.
+
+## [0.1.4] - 2026-09-14
+
+- Published the browser-safe package entry points to JSR under
+  `@swiftools/canvas-globe`.
+- Made generated UMD builds deterministic across Windows and Linux.
+- Corrected the custom-element render event and world-data type contracts.
+
 ## [0.1.3] - 2026-09-14
 
 - Added JSR package configuration and tokenless GitHub publishing workflow.

package/README.md

@@ -7,8 +7,9 @@
 [![GPL-3.0-only](https://img.shields.io/npm/l/canvas-globe.svg)](LICENSE)
 [![TypeScript declarations](https://img.shields.io/badge/types-included-3178c6.svg)](types/index.d.ts)
 [![zero runtime dependencies](https://img.shields.io/badge/runtime_dependencies-0-2ea44f.svg)](package.json)
+[![Agent skill](https://img.shields.io/badge/agent_skill-install-111827.svg)](https://skills.sh/Shree-hari/canvas-globe)
 
-[![CanvasGlobe interactive JavaScript globe with markers and animated routes](https://raw.githubusercontent.com/Shree-hari/canvas-globe/main/assets/readme/canvas-globe-hero.webp)](https://canvasglobe.swiftools.com/playground)
+[![Animated CanvasGlobe demo cycling through interactive globe themes, markers, and routes](https://raw.githubusercontent.com/Shree-hari/canvas-globe/main/assets/readme/canvas-globe-demo.gif)](https://canvasglobe.swiftools.com/playground)
 
 [**Open the live playground**](https://canvasglobe.swiftools.com/playground) ·
 [Examples](https://canvasglobe.swiftools.com/examples) ·
@@ -20,6 +21,10 @@
 [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz_small.svg)](https://stackblitz.com/github/Shree-hari/canvas-globe?startScript=start)
 [![Open in CodeSandbox](https://img.shields.io/badge/Open_in-CodeSandbox-151515?logo=codesandbox)](https://codesandbox.io/p/github/Shree-hari/canvas-globe)
 
+**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)
+
+**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, or a Web Component and requires no WebGL, map API
@@ -107,7 +112,7 @@ npx jsr add @swiftools/canvas-globe
 You can also import the JSR release directly in Deno:
 
 ```js
-import { createGlobe } from "jsr:@swiftools/canvas-globe@0.1.3";
+import { createGlobe } from "jsr:@swiftools/canvas-globe@0.1.5";
 ```
 
 The React entry point remains on npm so React's peer dependency is resolved by
@@ -118,19 +123,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@0.1.3/dist/canvas-globe.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/canvas-globe@0.1.5/dist/canvas-globe.umd.js"></script>
 ```
 
 The same npm release is also available from UNPKG:
 
 ```html
-<script src="https://unpkg.com/canvas-globe@0.1.3/dist/canvas-globe.umd.js"></script>
+<script src="https://unpkg.com/canvas-globe@0.1.5/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@0.1.3";
+import { createGlobe } from "https://esm.sh/canvas-globe@0.1.5";
 ```
 
 Pin an exact version in production so a future release cannot change a deployed page unexpectedly.
@@ -150,7 +155,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@0.1.3/dist/canvas-globe.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/canvas-globe@0.1.5/dist/canvas-globe.umd.js"></script>
 <canvas id="globe" style="width:520px;aspect-ratio:1"></canvas>
 <script>
   CanvasGlobe.createGlobe(document.getElementById("globe"), {
@@ -227,6 +232,29 @@ export function Visitors({ markers }) {
 
 React is an optional peer dependency: only the `/react` entry point needs it.
 
+For a dedicated React package name, install the thin companion entry point:
+
+```bash
+npm install react-canvas-globe
+```
+
+To scaffold a complete starter for React, Next.js, Vue, SvelteKit, Vanilla
+JavaScript, or Web Components, run:
+
+```bash
+npm create canvas-globe@latest my-globe
+```
+
+### AI-assisted setup
+
+Install the repository's CanvasGlobe skill for compatible coding agents:
+
+```bash
+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 a real license key before shipping. Proprietary projects are directed to [commercial pricing](https://canvasglobe.swiftools.com/pricing); GPLv3-compatible projects are directed to the [GPL licensing path](https://canvasglobe.swiftools.com/licensing).
+
 ## Options
 
 | Option | Default | Description |
@@ -700,8 +728,13 @@ npm test        # node --test, no test framework to install
 npm run build   # dist/canvas-globe.umd.js, with a gzipped size budget
 npm run example # demo at http://localhost:8099
 npm run release:check # tests, types, build and packed-artifact validation
+npm run capture:readme # regenerate the animated README demo with Chrome or Chromium
 ```
 
+The README capture script detects common Chrome and Chromium locations. If the
+browser is installed elsewhere, set `CANVAS_GLOBE_CHROME` to its executable
+path before running `npm run capture:readme`.
+
 The product website and documentation are maintained separately at
 [canvasglobe.swiftools.com](https://canvasglobe.swiftools.com/).
 

package/codemeta.json

@@ -5,7 +5,7 @@
   "identifier": "canvas-globe",
   "description": "Zero-dependency JavaScript and React library for interactive 3D globes and flat world maps rendered with Canvas 2D, with no WebGL or API-key requirement.",
   "url": "https://canvasglobe.swiftools.com/",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canvas-globe",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Zero-dependency JavaScript and React library for interactive 3D globes and flat world maps rendered with Canvas 2D. No WebGL or API key.",
   "license": "GPL-3.0-only",
   "author": {
@@ -92,10 +92,16 @@
     "build": "node scripts/build.mjs",
     "data": "node scripts/generate-data.mjs && node scripts/generate-timezones.mjs",
     "example": "node scripts/serve.mjs",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "build:registry": "shadcn build --output .registry-build",
+    "capture:readme": "node scripts/capture-readme-demo.mjs",
     "test": "node --test",
+    "test:ecosystem": "npm run build:registry && node scripts/validate-ecosystem.mjs && npm --prefix packages/create-canvas-globe test",
     "typecheck": "tsc --noEmit -p tsconfig.json",
+    "typecheck:ecosystem": "tsc --noEmit -p tsconfig.ecosystem.json",
     "smoke:package": "node scripts/package-smoke.mjs",
-    "release:check": "npm run test && npm run typecheck && npm run build && node scripts/release-check.mjs && npm run smoke:package",
+    "release:check": "npm run test && npm run typecheck && npm run typecheck:ecosystem && npm run test:ecosystem && npm run build && node scripts/release-check.mjs && npm run smoke:package",
     "prepublishOnly": "npm run test && npm run typecheck && npm run build && node scripts/release-check.mjs"
   },
   "peerDependencies": {
@@ -107,7 +113,16 @@
     }
   },
   "devDependencies": {
+    "@storybook/addon-a11y": "^10.6.0",
+    "@storybook/html-vite": "^10.6.0",
+    "@types/react": "^19.3.0",
+    "chromatic": "^18.8.1",
+    "gifenc": "^1.0.3",
+    "playwright-core": "^1.63.0",
+    "pngjs": "^7.0.0",
     "polygon-clipping": "^0.15.7",
+    "shadcn": "^4.21.0",
+    "storybook": "^10.6.0",
     "topojson-client": "^3.1.0",
     "typescript": "^5.5.0"
   },

package/src/element.js

@@ -1,4 +1,4 @@
-/* @ts-self-types="../types/element.d.ts" */
+/* @ts-self-types="../types/jsr-element.d.ts" */
 
 /**
  * `<geo-globe>` custom element. Wraps GeoGlobe so it can be dropped into any

package/src/react.js

@@ -1,10 +1,12 @@
+"use client";
+
 /* @ts-self-types="../types/react.d.ts" */
 
 /**
  * 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 { createElement, forwardRef, useEffect, useImperativeHandle, useRef, useState } from "react";
 import { GeoGlobe } from "./geo-globe.js";
 import { mapAspect } from "./geo.js";
 
@@ -17,6 +19,7 @@ export const Globe = forwardRef(function Globe(props, ref) {
 
   const canvasRef = useRef(null);
   const globeRef = useRef(null);
+  const [globe, setGlobe] = useState(null);
   const handlers = useRef(props);
   const previous = useRef(null);
   const initial = useRef(options);
@@ -27,6 +30,7 @@ export const Globe = forwardRef(function Globe(props, ref) {
     for (const name of CALLBACKS) bound[name] = (...args) => handlers.current[name]?.(...args);
     const globe = new GeoGlobe(canvasRef.current, { ...initial.current, ...bound });
     globeRef.current = globe;
+    setGlobe(globe);
     previous.current = initial.current;
     return () => {
       globe.destroy();
@@ -49,7 +53,7 @@ export const Globe = forwardRef(function Globe(props, ref) {
     if (changed) globe.setOptions(patch);
   });
 
-  useImperativeHandle(ref, () => globeRef.current);
+  useImperativeHandle(ref, () => globe, [globe]);
 
   const aspect = options.mode === "map" ? 1 / mapAspect(options.latRange, options.projection) : 1;
   return createElement("canvas", {