Clio Renderer Tour — basemaps + overlays.

Commands like [map.highlight] are Stagehand directives — they control the map renderer and pass through schema validation before any visual effect reaches the public output.

[scene.title kind=intro title="Clio Renderer Tour" subtitle="Track B Phase 1 — basemaps + overlays"]
[map.view lat=20 lon=0 zoom=1.5]

Clio's renderer can now swap basemaps and stack raster overlays on top of the editorial layers. Every swap fades smoothly. Every overlay carries its own license and attribution. Every command is one bracket in the script.

The default basemap is the MapLibre demo style. Continent fills and place labels, with editorial highlights and arrows layered above.

[scene.title kind=clear]
[scene.title kind=chapter title="Streets" subtitle="OpenStreetMap raster tiles"]
[map.fit entities=city:new_york padding=120 maxZoom=8]
[map.basemap streets]

When the story moves to street scale, the OSM raster basemap shows roads, neighborhoods, transit, and labels at the resolution scripts need for civic-intelligence beats.

Mamdani's New York at street detail. Mondragón in Arrasate. The Strait of Hormuz at port detail. All reachable now without leaving the Stagehand grammar.

The fade is 800 milliseconds. Long enough that the swap reads as deliberate; short enough that nothing feels stuck.

[scene.title kind=clear]
[scene.title kind=chapter title="Dark editorial" subtitle="CARTO Dark Matter — the foreground pops"]
[map.fit entities=country:united_states,country:china padding=160]
[map.basemap id="basemap:carto_dark"]
[map.highlight entity=country:united_states color="#3b82f6" opacity=0.55]
[map.highlight entity=country:china color="#ef4444" opacity=0.55]

For editorial chapters that want to feature one or two entities without competing detail, the CARTO Dark basemap pulls back. Country fills, arrows, asset cards, source citations — anything Clio paints on top reads cleanly against the muted background.

The US in blue. China in red. Same script grammar. Different visual register, set by a single command.

[scene.title kind=clear]
[map.clear highlights]
[scene.title kind=chapter title="Satellite" subtitle="NASA Blue Marble — public domain"]
[map.view lat=20 lon=0 zoom=2]
[map.basemap satellite]

For the satellite frame, NASA's Blue Marble composite gives the planet at low and medium zoom. Public domain, no API key, optimized for the orbital scale.

The same scripts that staged country highlights now have a real Earth underneath them. Continents read as land mass, not as colored polygons. Oceans read as water, not as flat fill.

[scene.title kind=clear]
[scene.title kind=chapter title="Nightlights" subtitle="NASA Earth at Night — VIIRS Black Marble"]
[map.fit entities=country:united_states padding=200]
[map.basemap nightlights]

For energy narratives, urbanization, infrastructure density — VIIRS Black Marble. The continental United States from orbit at night.

Every cluster of light is a population center, an oil field flare, a port complex, a shipping lane, a refinery, a freight hub. The Bakken in North Dakota glows like a small city. The Eastern Seaboard reads as one continuous urban smear from Boston to Norfolk.

[scene.title kind=clear]
[scene.title kind=chapter title="Raster overlays" subtitle="MODIS Terra true-color, today"]
[map.basemap dark]
[map.fit entities=country:united_states padding=160]
[map.overlay.show id="overlay:nasa_modis_terra_truecolor" opacity=0.85]

On top of the dark basemap, the MODIS Terra true-color overlay paints today's cloud cover, wildfires, snowpack, and dust.

Overlays are additive. Multiple layers can coexist, each with its own opacity. The Stagehand command grammar exposes the whole stack — one command sets the base, one command adds each layer on top, one command peels them off.

[scene.title kind=clear]
[map.overlay.hide]
[scene.title kind=chapter title="Back to default" subtitle="The renderer remembers the editorial frame"]
[map.basemap default]
[map.view lat=20 lon=0 zoom=1.5]

When the basemap returns to default, every editorial layer Clio painted stays exactly where it was. The basemap swap is wholesale at the raster level; everything above it is untouched.

That's the contract: basemaps are the canvas, overlays are the layers, editorial primitives are the paint. Each one swaps without disturbing the others.

[scene.title kind=clear]
[scene.title kind=outro title="Track B Phase 1" subtitle="Schema · renderer · MCP · tested"]
[map.view lat=20 lon=0 zoom=1.5]

Track B Phase 1 ships six basemaps and one demonstration raster overlay, with the renderer plumbing for both. The next phases bring infrastructure overlays, resource overlays, water, weather, and a global vector layer set.

Each lands as its own typed record with explicit license, ready for the script-writing loop to query and stage.