llms-full.txt@public git:20261005.73894b7A

Immutable. This exact content never changes and is served at /api/v1/blob/9ffb10d7f2212da2.

# Globestudio: Full LLM Reference

> Open-source, designer-first generator of dotted-style world maps and 3D
> globes that runs entirely in the browser. React + Three.js (WebGL2), 21
> looks, 5 flat projections for solid maps (dotted maps use Mercator),
> custom GeoJSON, PNG / SVG / WebM / MP4 / GIF / JSON export and embeds. MIT
> licensed. Targets WCAG 2.2 AA. NOT a GIS tool: a visual generator that
> an AI assistant can drive programmatically.

This is the expanded reference. The short version is at
<https://globestudio.app/llms.txt>.

## Driving Globestudio programmatically (for AI assistants)

The most direct path: build an `/embed?…` URL and drop it into an iframe, open
it for a screenshot, or hand it to the user. The `/embed` route is the canvas
only (no app chrome) and works in any client. No MCP required.

```
https://globestudio.app/embed?look=halftone&density=50&selection=continent:Europe&autoSpin=1
```

For full control, encode a complete config object and pass it as `?c=<json>`
(the same payload the in-app Share dialog produces). A JSON Schema for that
config is published at <https://globestudio.app/schema/config.json>. Editors
that read `$schema` autocomplete + validate it.

To change a look, send only the changes: `/looks/<id>?c=<json>` and
`/embed?look=<id>&c=<json>` layer the config over that look. A nested object
such as `globeSettings` or `shaderSettings` keeps the look's value for every
key it leaves out, so adding `dataPoints` to Sonar keeps its glow and grid off.
Leave `version` out of such a config: the studio writes it into every design
it saves, and a config that carries it gets the app defaults for those keys.

### MCP server

Globestudio runs a hosted MCP server at **`https://globestudio.app/mcp`**
(streamable HTTP, stateless, no install, no auth). Connect it by URL:

- Claude app (claude.ai, Desktop): Customize, Connectors, then + and Add custom
  connector. Paste the URL.
- Claude Code: `claude mcp add --transport http globestudio https://globestudio.app/mcp`
- Codex: `codex mcp add globestudio --url https://globestudio.app/mcp`
- Cursor: `{ "mcpServers": { "globestudio": { "url": "https://globestudio.app/mcp" } } }`
  in `~/.cursor/mcp.json`.

Tools: `list_presets`, `find_presets`, `build_share_url`, `embed_snippet`,
`preview_url`, and `read_share_url`, which decodes a share link the user pastes
(`/?c=…`, `/looks/<id>?c=…` or an `/embed` URL) into its look and settings so
you can change it and hand back a new link. The same tools run locally as
**`@globestudio/mcp`** (`npx -y @globestudio/mcp`).

A user without an MCP client can press **Copy for AI** in the export dialog's
MCP tab. It copies a plain text prompt with the share link, the key
settings, and what an agent can do with them.

The export dialog's Share tab has **Embed code** for the design on screen:
an iframe pointed at `/embed?c=…`, a `<Globe config=… />` snippet for
`@globestudio/react`, and a `<globe-studio config="…">` tag for
`@globestudio/element` loaded from esm.sh. Each has a Copy button. **Open in
CodePen** posts the web component version to CodePen's prefill API and opens
the pen in a new tab.

### Common URL parameters

- `look`: a preset id (see the catalog below), e.g. `look=crt`.
- `selection`: what to draw (see Selection reference below).
- `density`: dot density, 1–90 (invalid values fall back to the preset's).
- `autoSpin`: `1` to auto-rotate the globe, `0` to hold still.
- `theme`: `light` flips the globe chrome (glow, grid, surface) to a
  graphite-on-cream palette for light host pages and turns the white ink of
  Halftone, Wireframe, Toon and Threshold graphite; anything else stays dark.
  Halftone, Toon and Threshold paint a dark page of their own, where that
  ink is lost, so pair it with `transparent=1` or a light `background` there.
  The packages take it as `theme="light"` (`<Globe>`, `<globe-studio>`), and
  embed.js as `data-theme="light"`.
- `motion`: accepted (0–100) but currently inert: parsed, no effect yet.
- `c`: the share-config payload, a full URL-encoded config JSON, the same
  object the in-app Share dialog produces. It overrides the preset and the
  simple params above. The complete parameter table lives at
  <https://github.com/alevizio/globestudio/blob/main/README.md#embed-parameters>.

## Selection reference

`selection` takes one of these prefixes:

- `world`: the whole planet.
- `country:<ISO3>`: one country by 3-letter ISO 3166-1 alpha-3 code
  (`USA`, `FRA`, `JPN`, `BRA`, `DEU`, …).
- `continent:<Name>`: `Africa`, `Asia`, `Europe`, `North America`,
  `South America`, `Oceania`.
- `subregion:<Name>`: a UN subregion, e.g. `Western Europe`, `South-Eastern Asia`.

For one US state, DC or territory, use `country:USA` and set `stateSelection`
in the `c` config to its postal code (`CA`) or its FIPS code (`06`). The
studio and embeds draw it. A code the app doesn't know is ignored: an embed
shows the whole country, and the studio keeps the state it showed last.

## Preset catalog (21 looks)

Each is at `https://globestudio.app/looks/<id>` (marketing page) or
`https://globestudio.app/embed?look=<id>` (canvas only):

- `default`: Default, clean cartography.
- `halftone`: Halftone, newspaper print, browser-rendered.
- `risograph`: Risograph, pink + cyan ink, misregistered on purpose.
- `newsprint`: Newsprint, CMYK, four plates, rotated like the pros.
- `aurora`: Aurora, northern-lights bands across the planet.
- `pixel`: Pixel, an 8-bit world atlas.
- `bayer`: Bayer, classic-Mac threshold dither.
- `atkinson`: Atkinson, Atkinson dither, sparser than Bayer.
- `wireframe`: Wireframe, edge-traced, like a hand-pulled print.
- `crt`: CRT, cathode-ray phosphor glow.
- `glitch`: Glitch, signal break, RGB split.
- `badtv`: Bad TV, analog tape decay.
- `bloom`: Bloom, atmosphere on fire.
- `metal`: Metal, liquid chrome, soft reflections.
- `iridescent`: Iridescent, holographic foil sticker.
- `pencil`: Pencil, pencil-traced continents.
- `corrupt`: Corrupt, datamosh corruption, on purpose.
- `toon`: Toon, cel-shaded pop-art world.
- `threshold`: Threshold, pure two-tone binary.
- `vapor`: Vapor, synthwave horizon, pastel split.
- `topographic`: Sonar, rings on a sonar screen.

## Exports

From the in-app export dialog: PNG (high-res, rendered at its own scale, not
the on-screen DPR), SVG, WebM and MP4 video, GIF, and a JSON config (the same
payload as `?c=`). **Copy image** on the Image tab puts the same PNG on the
clipboard instead of saving a file, where the browser can write images there.
SVG and the Figma tab's **Copy as vectors** draw the flat map, even from
the globe view, and keep the dots, their shapes and colors. A look's shader
effect, solid land and a Space or Flow background come through only in PNG
or video, so of the looks only `default` exports to SVG whole; when the
design has something the vectors leave out, both tabs name it and point to
the image.
Rendering is client-side; there is no server-side image
endpoint (yet). For a screenshot, point a headless browser at an `/embed?…`
URL.

## Docs + code

- README: <https://github.com/alevizio/globestudio/blob/main/README.md>
- Embed parameters (the canonical table):
  <https://github.com/alevizio/globestudio/blob/main/README.md#embed-parameters>
- Integrations (Webflow / Framer / Figma / Notion / WordPress / plain HTML /
  React, per-tool setup): <https://globestudio.app/integrations>
- WordPress: works via a Custom HTML embed (<https://globestudio.app/integrations>). A block plugin is in the repo, not yet on wordpress.org: <https://github.com/alevizio/globestudio/blob/main/wordpress-plugin/globestudio/README.md>
- MCP server: hosted at <https://globestudio.app/mcp>; tool list + setup at
  <https://github.com/alevizio/globestudio/blob/main/packages/mcp/README.md>
- JSON Schema: <https://globestudio.app/schema/config.json>
- React component (`npm i @globestudio/react`): <https://www.npmjs.com/package/@globestudio/react>
- React starter, a Vite app with a globe on the page
  (`npx degit alevizio/globestudio/examples/starter-react my-globe`):
  <https://github.com/alevizio/globestudio/tree/main/examples/starter-react>,
  or open it in StackBlitz:
  <https://stackblitz.com/github/alevizio/globestudio/tree/main/examples/starter-react>
- Script-tag loader: <https://globestudio.app/embed.js>

## Constraints to remember

- 3-letter ISO 3166-1 alpha-3 country codes only.
- `/embed` = canvas only (use for iframes); `/looks/:id` = full marketing page
  (use for share links, not iframes).
- WebGL2 required; the embed falls back gracefully when GL is unavailable, but
  functionality is degraded.
- Rendering is client-side; there is no server-side render endpoint yet.
- Keep an embed address under 32,000 characters: the site turns away one a
  little longer. The config rides in it URL encoded, so a custom shape file
  or a long list of data points may not fit.
- `globeSettings.dataPoints` keeps the first 250 points with a valid `lat`
  and `lng`.
- MIT licensed. The visuals you export are yours; redistributing the source or
  built bundle requires keeping the LICENSE + NOTICE files (NOTICE credits
  Pixelarticons and the open atlases the tool relies on).

## FAQ

### What is Globestudio?

Globestudio is a designer-first, open-source web tool for creating dotted maps
and animated 3D globes. Pick any country, region, or US state, customize dot
shapes, gradients, and WebGL shader effects, then export PNG, SVG, WebM, MP4 or
GIF, a JSON config, or an embed. It runs in the browser with no account or
install.

### Is Globestudio free to use commercially?

Yes. Globestudio is MIT-licensed, so you can use it commercially without
paying. MIT requires you to keep the LICENSE + NOTICE files when redistributing
the source or built bundle (NOTICE credits Pixelarticons and the open atlases
the tool relies on). The visuals you export (PNG, SVG, WebM, MP4, GIF, JSON)
are yours; no attribution needed on the exports themselves. Rendering and
exports run client-side in your browser; your designs are never uploaded.

### How do I export a dotted globe?

Press D or click the Export button to open the export dialog. PNG exports
re-render the canvas at up to 4x resolution, and Copy image puts that PNG on
the clipboard to paste elsewhere; SVG exports produce vector output
for print or further editing, and the SVG tab says when the look has an
effect only the PNG keeps; WebM, MP4 and GIF exports record the live
animation; JSON exports save the full config so others can reproduce your look.

### Does Globestudio work on mobile?

Yes. Globestudio works on modern mobile browsers (iOS Safari 15.4+, Chrome for
Android, Samsung Internet) that support WebGL 2. The interface adapts to small
viewports; the panel hides on first visit so the visual is the first
impression.

### What design tools does Globestudio integrate with?

The Globestudio Figma plugin, in the Figma Community, inserts a globe into your
file. Paste a share link into the plugin (a `/?c=…`, `/looks/<id>` or `/embed`
link) and that exact design loads there, ready to insert. Without the plugin,
the export dialog's Figma tab copies the design as vectors or as an image,
ready to paste into a Figma file (the tab is left out
on phones). It says when the look has an effect the vectors can't keep.
For websites, paste the iframe or the one-line script embed into Webflow,
Framer or plain HTML, or the embed URL into Notion; it works in WordPress via a
Custom HTML embed. React apps can use @globestudio/react, and AI assistants can
use the @globestudio/mcp server. PNG and SVG exports drop into any design tool:
Figma, Sketch, Adobe Illustrator, Affinity Designer.

### Can I animate the globe?

Yes. The globe view supports auto-spin, dot rotation, twinkle, size variance,
and animated network arcs. WebM, MP4 and GIF exports capture the live
animation; all motion respects the user's prefers-reduced-motion preference
automatically.

### What browsers are supported?

Globestudio requires WebGL 2 (~95% global support as of 2026). Chrome 56+,
Firefox 51+, Safari 15.2+, Edge 79+, Samsung Internet 7.2+, and Chrome for
Android 58+ all work. On older hardware (e.g. Intel HD 3000) WebGL 2 may not be
available; in that case the tool shows a fallback message.

### How is Globestudio different from a generic map library?

Globestudio is not a GIS tool. It is a curated motion-design tool focused on
one aesthetic, dotted maps and animated globes, with deep control over visual
styling (shaders, gradients, shapes). Generic libraries like Mapbox or Leaflet
target geocoding, tile servers, and routing; Globestudio targets designers
shipping landing pages, decks, and motion graphics.