Interactive Map Builder

Turn existing spatial data into searchable, presentation-ready, verified map products with an AI agent.

Product homepage · 中文说明 · Releases · Changelog

Interactive Map Builder is a Codex-first Agent Skill for turning existing spatial data into portable map products. Describe the outcome in ordinary language, attach GeoJSON, GeoPackage, Shapefile, CSV, Excel, or ArcGIS data, and the Agent inspects the inputs, resolves build-critical requirements, writes an auditable MapSpec, builds the appropriate map product, and verifies the final handoff.

Existing spatial data → inspect → confirm → MapSpec → build → verify → portable HTML + optional figures

The product stays map-first and focuses on finding spatial objects, understanding spatial context, saving important viewpoints, and delivering the result through one interactive map interface.

Core product capabilities

• Search & filter. Find records by name or attributes, filter categories and numeric ranges, sort results, and inspect feature details directly in the browser.
• Layer control. Move between a neutral overview and layer-focused exploration while controlling visibility, legends, and basemaps independently.
• Saved Views. Save up to eight named center-and-zoom positions in the current browser, then return to Overview or key sites during exploration and presentation. Saved Views use browser-local state and stay separate from MapSpec and the delivered HTML file.
• Portable delivery. Deliver a self-contained map.html and generate 16:9 or publication PNG/SVG/PDF outputs from the same visual plan.

Two map products

Map + list	Multilayer
Map + list. Find, filter, sort, and compare records through linked list-map interaction, KPI summaries, and a detail panel. Best for parcels, buildings, facilities, stores, projects, events, or candidate sites.	Multilayer. Explore several independent spatial themes from Overview, focus one searchable layer, control visibility separately, inspect feature details, and save key map views. Best for boundaries, roads, routes, facilities, environmental layers, and planning context.
Open live map →	Open live map →

Both live maps are generated by the repository's deterministic engine from fixed NYC Open Data snapshots. The screenshots and live demos show those generated product outputs directly.

Explore → Focus → Present

flowchart LR
    A["Explore<br/>Search · filter · switch layers"] --> B["Focus<br/>Inspect one place in context"]
    B --> C["Present<br/>Save and revisit key views"]

A common workflow starts with the whole map, narrows to one or more important sites, and returns to those exact map positions during a meeting or review. Saved Views completes that flow by recording browser-local Center + Zoom state, keeping a fixed Overview entry, supporting rename/delete, and remaining separate from the map's data and MapSpec contract.

Describe the outcome

The Skill is designed to activate from requests like these:

This Excel sheet has longitude and latitude. Make a browser page where I can search facilities,
filter by type, click a record, and share the result.

Combine the parcel, road, water, green-space, and parking layers into one planning presentation
map with layer switches, object details, and a few viewpoints I can return to while presenting.

Turn these existing layers into one portable HTML file and export a 16:9 figure for the meeting.

Users can invoke $interactive-map-builder explicitly, and natural-language outcome requests also activate the Skill.

Quick start

1. Install the Skill in Codex

Open a new Codex task and send:

$skill-installer Install the Skill from https://github.com/xlbaoxl/interactive-map-builder and install its Python dependencies. Run interactive-map-builder doctor and interactive-map-builder update --preflight after installation.

Create a new task after installation. If the Skill does not appear, restart Codex once. Starting with v0.4.3, repository-copy installs whose Release-owned files match the checksum-verified official package can enter managed updates automatically.

2. Attach spatial data and describe the result

Turn my attached spatial data into a searchable, filterable interactive map. Use English for the map audience and export a 16:9 presentation figure.

The Skill first inspects the inputs, then keeps a compact requirements checklist while choices remain unresolved:

- [x] Confirmed: supplied by the user or established by the data
- [~] Inferred: proposed by the Skill and easy to revise
- [ ] Needs confirmation: required before the build can start

It groups build-critical choices into one confirmation round, including CRS, template, primary layer, category meaning, display fields, output formats, and audience locale.

3. Verify the installation

interactive-map-builder doctor
interactive-map-builder update --preflight

doctor runs an offline verification in a temporary workspace: it creates a coordinate table, builds a map with the packaged Leaflet resources, verifies output hashes, prints a JSON result, and removes the temporary files. The update command prints structured JSON containing the local version, official version when known, source, installation type, and status. For a cached status query, run interactive-map-builder update --check.

Prefer interactive-map-builder doctor after installation. In a source checkout where the console command is not yet available, use python scripts/cli.py doctor. The formal doctor entry point is interactive-map-builder doctor; python scripts/map_builder.py --help lists the internal build commands.

Keep one active Codex Skill directory. A legacy Windows location may be $HOME\.agents\skills; archive it before using the active Codex directory below.

Windows PowerShell

$CodexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { "$HOME\.codex" }
New-Item -ItemType Directory -Force "$CodexHome\skills" | Out-Null
git clone https://github.com/xlbaoxl/interactive-map-builder.git `
  "$CodexHome\skills\interactive-map-builder"
Set-Location "$CodexHome\skills\interactive-map-builder"
py -m pip install .
interactive-map-builder doctor
interactive-map-builder update --preflight

macOS or Linux

CODEX_ROOT="${CODEX_HOME:-$HOME/.codex}"
mkdir -p "$CODEX_ROOT/skills"
git clone https://github.com/xlbaoxl/interactive-map-builder.git \
  "$CODEX_ROOT/skills/interactive-map-builder"
cd "$CODEX_ROOT/skills/interactive-map-builder"
python3 -m pip install .
interactive-map-builder doctor
interactive-map-builder update --preflight

Every v0.3.1+ GitHub Release publishes:

• interactive-map-builder-skill-vX.Y.Z.zip — a lean Agent Skill package containing SKILL.md, Agent metadata, references, the deterministic engine, and its packaged web resources;
• a Python wheel and source archive for conventional package installation;
• SHA256SUMS.txt for release-asset verification and managed Skill updates.

The Skill ZIP focuses on runtime delivery. Demos, screenshots, tests, and CI stay in the full repository. Extract the ZIP into an Agent Skills directory, run python -m pip install ., then run interactive-map-builder doctor.

Copy the complete repository or the versioned Skill ZIP into a Skill or rules directory that the client can read, let it load SKILL.md, and install the deterministic engine once:

python -m pip install .
interactive-map-builder doctor

The workflow is client-neutral: inspect data, maintain the requirements checklist, write the canonical MapSpec, build with the packaged engine, verify, and deliver the complete dist directory.

Built for reliable handoff

Product interactions and delivery use one deterministic build path:

User request + spatial files
           │
           ▼
       inspect inputs
  CRS · geometry · fields · scale
           │
           ▼
  confirm unresolved intent once
           │
           ▼
        MapSpec 1.1
           │
           ▼
 Atlas Studio Light resolver
 geometry · density · role · order
           │
           ▼
 deterministic Python engine
 load · normalize · render
           │
           ▼
 verify counts, files, QA hooks,
 provenance, hashes, and browser UI
           │
           ▼
  portable HTML + report figures

The packaged JSON Schema defines the machine-readable MapSpec contract. Canonical keys use snake_case, and the schema validates the supported fields and schema versions strictly.

Updates, planning, and public deployment

At the start of a Skill task, the Agent runs interactive-map-builder update --preflight from the Skill root. The command checks release status, reuses a valid result for up to 24 hours, preserves the current installation, and reports new-version or check-status information when relevant. Map construction remains available offline. Set IMB_DISABLE_AUTO_UPDATE=1 to disable the check.

Applying an update is a separate maintenance action. update --apply and the legacy non-fatal update --auto --force retain checksum, manifest, exact-copy adoption, local-change protection, duplicate-root refusal, post-install doctor verification, and rollback.

Version v0.4.3 introduced copy-install adoption. Existing unmanaged v0.3.2–v0.4.2 copies can move into the managed update flow through one official v0.4.3 reinstall, after which compatible releases can be adopted and applied automatically.

Updates are transactional: after replacing a verified release, the updater reinstalls the engine and runs the offline doctor. Recovery restores the prior Git commit or previous manifest-owned files when installation or verification does not complete successfully. Confirmed release metadata stays available throughout the recovery flow. See the verified update policy.

For complex Codex tasks—multiple independent layers, several design choices, or coordinated HTML/slide/paper outputs—the Agent may suggest Plan mode once as an optional convenience. Data inspection continues immediately, while clear single-layer requests move directly into the standard workflow.

The normal deliverable is a portable local map.html, ready to send to colleagues. Public URL requests enter a dedicated deployment flow that confirms the hosting target and data-publication permissions. Hosting is handled as a separate delivery workflow alongside local map construction.

Atlas Studio Light

Version 0.4 introduces a lightweight visual-default resolver rather than a full automatic design system. When MapSpec omits low-level visual values, the engine uses geometry family, coarse feature/coordinate density, template role, and stable draw order to choose a restrained first render:

• dense point layers use smaller symbols and lower fill intensity;
• lines and polygons receive separate weights, fills, and outlines;
• map-list primary layers stay prominent while context layers recede;
• multilayer maps open with all visible layers at their base style, then focus a layer only after the user selects it;
• HTML, legends, cards, PNG, SVG, and PDF consume the same resolved visual plan;
• automatic categorical colors stop at eight distinct classes instead of cycling into a rainbow.

Explicit MapSpec values always win. The goal is a credible, presentation-ready starting point—not a replacement for a planner or designer. Users can keep refining color, size, opacity, fields, and hierarchy through natural-language instructions or direct MapSpec edits. Every inferred decision is recorded in build_report.json under visual and visual_system.

Product behavior and controls

A map-list may include context layers in addition to its primary searchable layer. A multilayer map keeps search focus separate from visibility: choosing one layer to browse does not hide other context layers. Both products include Saved Views, and both use the same resolved visual plan for map rendering and legends.

New MapSpec files include two credential-free online basemaps: CARTO Positron as the quiet default and OpenStreetMap Standard for detailed street context. The selector also includes No basemap, and repeated tile failures automatically fall back to it, so business layers and interactions remain usable without tiles. Esri World Imagery can be added only when the user provides an authorized service URL or token and accepts that browser-delivered credentials can be visible in the generated HTML.

In the multilayer product, visibility switches are kept in a fixed upper section. The legend is stacked below them, scrolls when long, and starts collapsed at narrow widths, so a large categorical legend cannot cover the layer controls.

Supported inputs

The inspection step reports feature count, geometry type, CRS, field samples, likely ID, label, and category roles, ambiguities, and performance signals before a map is proposed.

Deliverables

A normal build keeps source paths relative to the original project and treats map_spec.json as a build record. Use --bundle-sources when the deliverable must rebuild independently after it is moved.

For one unambiguous layer:

interactive-map-builder run data.geojson --locale en-US --output dist

For an explicit, reproducible workflow:

interactive-map-builder inspect sites.geojson districts.geojson \
  --output inspection.json

interactive-map-builder init-spec inspection.json \
  --template map-list \
  --primary-layer sites \
  --locale en-US \
  --output map_spec.json

interactive-map-builder build --spec map_spec.json --out dist --bundle-sources
interactive-map-builder verify --dist dist

For independent point, line, and polygon layers, use --template multilayer and omit --primary-layer.

Scope

Interactive Map Builder focuses on existing spatial data → finished map product. It does not currently provide:

• address geocoding;
• buffers, overlays, routing, site-selection models, or statistical inference;
• vector-tile services or million-feature WebGIS infrastructure;
• offline basemap acquisition;
• CRS guessing from coordinate ranges;
• 3D terrain, buildings, or digital twins;
• general maintenance of an existing custom Leaflet or React application;
• automatic public hosting without an explicit deployment request and data-publication approval.

For large GeoJSON payloads, the build report recommends light or medium geometry simplification but does not silently switch rendering engines.

Project status

The current stable release is v0.5.1. Version 0.5 introduced browser-persistent Saved Views to both existing map products; 0.5.1 keeps Overview, Save View, and management controls visible when a larger saved-view list needs horizontal scrolling. MapSpec remains 1.1 and the two template families remain unchanged.

See the changelog for completed work.

Development

python -m pip install -r requirements-dev.txt
python scripts/evaluate_triggers.py validate
python -m pytest -q -m "not browser"
python -m playwright install chromium
python -m pytest -q -m browser

Build the localized demo site and lean Skill package:

python scripts/build_demo_site.py --output _site
python scripts/build_skill_package.py

The CI matrix covers Python 3.9–3.12, trigger-suite validation, Chromium interaction tests, wheel creation, the offline installation doctor, Windows smoke tests, a clean out-of-repository build, and the Skill distribution archive. After a new package version passes main CI, the Release workflow creates the tag and assets or repairs an incomplete Release without moving an existing tag.

License

MIT