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, closes only blocking requirements gaps, 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 deliberately map-first: it helps people find spatial objects, understand them in context, save important viewpoints, and deliver the result without turning the browser page into a generic BI dashboard.

Core product capabilities

• Search & filter. Find records by name or attributes, filter categories and numeric ranges, sort results, and inspect feature details without reopening desktop GIS.
• 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 do not change MapSpec or mutate the delivered HTML file.
• Portable delivery. Deliver a self-contained map.html; generate 16:9 or publication PNG/SVG/PDF outputs only when they are explicitly requested.

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. They are real outputs, not separate design mockups.

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 then needs to return to those exact map positions during a meeting or review. Saved Views completes that flow: it records only browser-local Center + Zoom state, keeps a fixed Overview entry, supports rename/delete, and remains separate from the map's data and MapSpec contract.

Ask for the outcome, not the tool

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.

My colleagues do not have ArcGIS. Turn these existing layers into one HTML file and export a 16:9
figure for the meeting.

The user can still invoke $interactive-map-builder explicitly, but naming the Skill is not required for a matching Agent task.

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. Restart Codex once only when the Skill does not appear. Starting with v0.4.3, a repository-copy install can become update-managed automatically only when all Release-owned files exactly match the checksum-verified official package.

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 asks one consolidated round only for blocking choices such as 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 creates a temporary coordinate table, builds a map without network access, verifies the packaged Leaflet resources and output hashes, prints a JSON result, and removes the temporary files. It does not download basemaps or send usage telemetry. The update command prints structured JSON containing the local version, official version when known, source, installation type, and status. For a cached status-only 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 internal python scripts/map_builder.py --help command intentionally lists only build commands and must not be used to conclude that the package lacks doctor.

Use one active Codex Skill directory rather than keeping duplicate .codex and .agents copies. 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 intentionally excludes demos, screenshots, tests, and CI files. Extract it 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

The product-facing interactions sit on one deterministic delivery path rather than separate ad hoc web pages:

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 is the only machine-readable MapSpec contract. Canonical keys use snake_case; unsupported fields and schema versions are rejected instead of being silently migrated.

Updates, planning, and public deployment

At the start of a Skill task, the Agent runs interactive-map-builder update --preflight from the Skill root. This is a cached, check-only request: it reuses a valid result for up to 24 hours, never modifies files, stays silent when the installed version is current, and reports only an available update or a failed check. Offline access never blocks map construction. Set IMB_DISABLE_AUTO_UPDATE=1 to opt out.

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.

Versions v0.3.2–v0.4.2 do not contain the copy-adoption fix. An already installed unmanaged copy of one of those versions needs one official v0.4.3 reinstall. Later compatible releases can then be adopted and applied automatically.

Updates are transactional: after replacing a verified release, the updater reinstalls the engine and runs the offline doctor. A failed install or doctor check restores the prior Git commit or the previous manifest-owned files. Confirmed release metadata is preserved when application fails, so an Agent cannot silently convert “an update is available” into “no update available.” See the verified update policy.

For a genuinely complex Codex task—multiple independent layers, several unresolved design choices, or coordinated HTML/slide/paper outputs—the Agent may suggest Plan mode once as an optional convenience. It continues inspecting immediately whether or not the user switches, and clear single-layer requests do not receive the suggestion.

The normal deliverable is a portable local map.html. “Share with colleagues” means sending that file, not publishing embedded data on the internet. A public URL is discussed only when explicitly requested, after confirming a hosting target and permission to expose the data. Hosting remains a separate workflow from 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