MapStage
MapStage is an open-source Skill for coding agents with a browser-based tuner for map and globe projections, satellite imagery, hypsometric relief, hillshade, 3D terrain, region isolation, and JSON preset export.
Project overview
MapStage turns map visual decisions into browser-adjustable parameters that a coding agent can carry into a real page. Its tuner supports flat-map and globe projections together with satellite imagery, hypsometric relief, hillshade, 3D terrain, region isolation, city tiers, and CSS color grading. Users can copy a JSON preset containing camera, resource, and style settings. The included Skill then guides an agent to migrate the preset into a production MapStage page and wait for the map's idle event before capture or export.
Core capabilities
Map and globe projections
Switch between a flat map and globe projection while adjusting center, zoom, bearing, and pitch.
Satellite, elevation, and terrain composition
Control satellite imagery and hypsometric relief independently, then add hillshade and 3D terrain backed by Mapterhorn Terrarium DEM data.
Region isolation and city tiers
Emphasize a target region with clipping and terrain-island effects, and display settlements by capital, large, medium, small, and other documented tiers.
JSON preset migration
Export camera, resource, and visual parameters so an agent can reproduce the tuned result in a production MapStage page.
Installation and usage
Clone the repository and copy the complete mapstage directory into the active agent host's Skills directory. Codex uses ~/.codex/skills/mapstage and Grok uses ~/.grok/skills/mapstage. Reload Skills, then start the local tuner and pass its exported JSON to the agent.
Let an AI Agent install it
Send this prompt to Codex, Claude Code, or another AI agent that can work with your local environment.
Help me install MapStage from https://github.com/hopechen067/MapStage. First read README.md, mapstage/SKILL.md, mapstage/tuner/README.md, LICENSE-EXCEPTIONS.md, DATA-PROVENANCE.md, and SECURITY.md. Select the documented Skills directory for the current agent host and copy only the complete mapstage directory. Ask before overwriting an existing directory, installing an additional runtime, requesting extra permissions, or asking for any credential. Reload Skills and confirm that MapStage is discoverable. Then run node verify.mjs under mapstage/tuner and use a local HTTP server for a minimal tuner load check. Report the installation path, verification result, and external data endpoints. Do not modify a production project, upload material, or publish a page without my confirmation.- Git
- A Codex or Grok client that supports Agent Skills
- Write access to the target Skills directory
- Python 3 or a Node.js environment that can run npx for the local tuner
- Network access to the default satellite, DEM, vector map, and CDN resources
git clone --depth 1 https://github.com/hopechen067/MapStage.git
cp -R MapStage/mapstage ~/.codex/skills/mapstage- 1Clone and copy the Skill
On macOS or Linux, run git clone --depth 1 https://github.com/hopechen067/MapStage.git cp -R MapStage/mapstage ~/.codex/skills/mapstage For Grok, use ~/.grok/skills/mapstage as the destination.
- 2Reload and confirm discovery
Restart or reload the agent client and confirm that MapStage is discoverable. Compare files and obtain approval before replacing an existing directory.
- 3Start the local tuner
Enter mapstage/tuner, run python -m http.server 8765, and open http://127.0.0.1:8765/. The documented alternative is npx --yes serve -l 8765.
- 4Tune and export a preset
Choose the map or globe projection, adjust satellite, elevation, terrain, region isolation, and camera settings, then use Copy JSON to save the result.
- 5Hand the preset to the agent
Paste the JSON into an agent session with MapStage loaded. Ask it to migrate the preset into the production page, use jumpTo for the final camera, and wait for map idle before capture or export.
Reload the client and confirm that the MapStage Skill is discoverable. Enter mapstage/tuner, run python -m http.server 8765, open http://127.0.0.1:8765/, and confirm that the map interface loads. Running node verify.mjs should print verify ok when the current tuner assets and static constraints pass.
- The README includes PowerShell copy commands for Windows, targeting .codex or .grok under the user profile.
- Serve the tuner over HTTP. Opening it with the file protocol causes resource-path and browser-loading problems.
- Keep local endpoint overrides in map-tiles.config.local.js, and never commit keys or private URLs.
- Default map and terrain data come from third parties. Review terms, attribution, quota, and availability before production use.
Use cases
Regional thematic maps
Highlight a province, river corridor, or route area with region isolation, hillshade, and city tiers.
Globe-view storytelling
Combine globe projection, satellite imagery, and camera settings for route, geopolitical, or natural-landscape opening scenes.
Map design handoff
Let a designer finalize the treatment in the tuner, export JSON, and have a coding agent reproduce it in the final page.
Assessment
MapStage concentrates map visual parameters that often require repeated trial and error into one browser tuner, then uses JSON to bridge visual decisions and agent implementation. Installation, production migration, data provenance, attribution, and security boundaries are documented in useful detail, and the included verifier checks key assets. The project is still new and has no formal release. Its default experience depends on several external network resources, and a few reference documents still contain legacy naming or an older water-overlay workflow. This review checked documentation, licenses, maintenance metadata, and the static verifier, but did not test visual output.
Why it may be useful
- Combines map, globe, satellite, elevation, terrain, and region isolation in one tuning workflow
- JSON presets support a clean handoff from visual tuning to agent implementation
- Separate documents cover license exceptions, data provenance, and third-party attribution
- The included verify.mjs checks key assets and selected configuration hazards
What to know first
- The repository is young and has no formal release
- Default output depends on third-party map and CDN availability and terms
- The local tuner is not a production host
- Some reference material retains legacy naming or an older water-overlay description
- Installation and visual output were not tested for this catalog entry
README
MapStage
Overview
MapStage is an open-source Skill for coding agents with a browser-based tuner for map and globe projections, satellite imagery, hypsometric relief, hillshade, 3D terrain, region isolation, and JSON preset export. MapStage live tuner: map/globe, satellite, hypsometric relief, region isolate, Mapterhorn DEM, JSON presets.
Getting started
- Clone the repository and copy the complete mapstage directory into the active agent host's Skills directory. Codex uses ~/.codex/skills/mapstage and Grok uses ~/.grok/skills/mapstage. Reload Skills, then start the local tuner and pass its exported JSON to the agent.
- The project provides the MapStage Agent Skill, a browser tuner, JSON presets, reference documents, and sample configuration.
- The tuner covers map and globe projections, satellite imagery, hypsometric relief, hillshade, 3D terrain, region isolation, and city tiers.
- Reload the client and confirm that the MapStage Skill is discoverable. Enter mapstage/tuner, run python -m http.server 8765, open http://127.0.0.1:8765/, and confirm that the map interface loads. Running node verify.mjs should print verify ok when the current tuner assets and static constraints pass.
Configuration
git clone --depth 1 https://github.com/hopechen067/MapStage.git
cp -R MapStage/mapstage ~/.codex/skills/mapstage