mapbox-ops - SKILL.md Agent Skill

name: mapbox-ops description: >- Advanced Mapbox GL JS toolkit for the WEB (mapbox-gl-js v3, not native/iOS): build production map experiences — custom markers, thematic dataviz, 3D, terrain, cinematic camera, style composition, performance, and hard-won gotchas. Use for Mapbox GL JS work: custom markers, addImage / updateImage, icon-image, SVG / canvas markers, icon-anchor / icon-offset, symbol layers, geojson layers, clustering, feature-state hover / select, queryRenderedFeatures, style expressions (interpolate / step / match / case, zoom-outermost rule), line-dasharray, line casing, line-gradient, hillshade, contours, setTerrain, raster-dem, fill-extrusion 3D buildings, heatmap, choropleth / data-join, proportional symbols, basemap palette recolour, setPaintProperty, v3 Standard style / slots / setConfigProperty / lightPreset, style switcher / library, text labels / text-optional, popups, flyTo / easeTo / freeCameraOptions camera animation, setStyle re-add, map.resize, WebGL teardown, or headless Playwright map verification. license: MIT compatibility: "Web mapbox-gl-js v3.x. screenshot_map.py needs Python 3.10+ and Playwright (chromium); check-mapbox-facts.py is stdlib-only Python 3.10+." metadata: author: claude-mods related-skills: "color-ops, screenshot"

Mapbox GL JS — advanced web toolkit (v3)

An advanced toolkit for building production Mapbox GL JS map experiences on the web: markers, thematic dataviz, 3D, terrain, cinematic camera, style composition, performance, and the hard-won gotchas that bite. Scope: mapbox-gl-js v3.x in the browser (CDN mapbox-gl-js/v3.x/) — not the native iOS/Android SDKs (different APIs). Plain GL JS, framework-agnostic. Several patterns were distilled from a production trail map; adapt the constants to your own design.

Setup invariants

Set mapboxgl.accessToken before new mapboxgl.Map(...).
The map needs 'load' before adding sources/layers/images. In a throttled or background tab 'load' can be missed — also bind 'idle' as a one-shot fallback guarded by an _inited flag (see verification.md).
Resolving token/style from .env: read the token FIRST (that triggers the .env load), THEN read MAPBOX_STYLE. Reading the style before the token load silently falls back to the default style. See palette.md.
Classic vs Standard style. Several techniques here (basemap palette recolour, the terrain boost-or-add getStyle().layers walk) assume a classic style (Streets/Outdoors/Light/Dark …-v12). The v3 default Standard style has no enumerable named layers — use slots + setConfigProperty instead. See v3-standard-style.md before porting to Standard.

Pick the technique

Read the matching reference file only when the task needs it:

Task	Reference
Custom SVG/canvas markers, `addImage`/`updateImage`, namespacing, AA/fringing, circular image masks, anchoring	references/markers.md
Dashed/cased trail lines, `line-dasharray` units, translucency over hillshade, colour-by-attribute, `line-gradient`/`lineMetrics`	references/lines-and-trails.md
Hillshade, dense contours, 3D terrain (`setTerrain`), boost-or-add an existing style's terrain	references/terrain.md
Symbol-layer text labels that never hide icons (`text-optional`), AllTrails-style placement	references/labels.md
Recolour a base style's land/vegetation fills (palette shift / choropleth-style `match`)	references/palette.md
Custom popups, circular photo cards, zoom-scaled offsets	references/popups.md
Style expressions — `interpolate`/`step`/`match`/`case`, the zoom-outermost rule, `feature-state` in expressions	references/expressions.md
Hover/select via `feature-state` (not `setData`), `queryRenderedFeatures` caveats, clustering, GeoJSON perf, event hygiene	references/interaction-and-performance.md
Data viz & 3D — `fill-extrusion` buildings/extruded data, heatmap layer, data-join choropleth (feature-state/`match`), proportional symbols, sky/fog	references/dataviz-and-3d.md
Camera & animation — `flyTo`/`easeTo`/`fitBounds` padding, `freeCameraOptions` cinematics/orbit, flight/first-person camera (roll, 6-DoF), animated day–night cycle (`setLights`), HUD synced to camera, point-along-line, draw-in lines, paint transitions, spinning globe, the `essential`/reduced-motion gotcha	references/camera-and-animation.md
Style library & composition — first-party style catalog, choosing a base by use case, custom/third-party styles, style switcher, light/dark, hand-rolled style JSON	references/styles.md (+ assets/style-catalog.json)
`setStyle` wiping custom layers, the 0×0 `resize()` bug, SPA teardown / WebGL-context cap, token security, readiness events	references/lifecycle.md
v3 Standard style — slots vs `beforeId`, `setConfigProperty`/`lightPreset`, why layer-walking (palette/terrain) breaks; localisation, RTL, globe	references/v3-standard-style.md
Headless screenshot + pixel-accurate marker-alignment checks (Playwright, `map.project`)	references/verification.md

Bundled resources

Starter code — assets/circular_image_marker.js: copy into a page to register a circular photo marker (canvas → premultiplied ImageBitmap, destination-in mask, contact + drop shadow). Browser-only snippet, not a CLI — adapt the frameColor/box constants to your design.

Verifier script — scripts/screenshot_map.py: drive headless Chromium to screenshot a served map page, assert a marker projects to its lng/lat, and surface console errors. Run it:

python -m http.server 8777 --directory <site-dir> &          # serve the page
uv run --with playwright scripts/screenshot_map.py \
  http://localhost:8777/preview/index.html out.png --expect 146.9 -36.1
# exit 0 = no console errors; 10 = errors found; 5 = playwright missing; 7 = map never ready
uv run --with playwright scripts/screenshot_map.py URL out.png --json | jq '.data'

Staleness verifier — scripts/check-mapbox-facts.py: stdlib-only (no Playwright), guards the fast-moving facts this skill encodes (SKILL-RESOURCE-PROTOCOL §7). --offline (default) asserts internal consistency — the v3 Standard config enums (lightPreset/theme), terrain tileset IDs, the weather (≥3.7) and camera-roll (≥3.5) version gates, and every style URL/id in assets/style-catalog.json. --live resolves the third-party style URLs and probes whether Mapbox GL JS has shipped a major past v3.
```
python scripts/check-mapbox-facts.py --offline            # exit 0 ok, 4 inconsistency
python scripts/check-mapbox-facts.py --live --json        # exit 7 network, 10 drift
```

The three highest-value gotchas (full detail in the refs)

Namespace every addImage name (e.g. "rcpin-<glyph>"). Mapbox styles ship sprite icons literally named parking/toilet/etc — an un-namespaced hasImage() returns true for those and your icon is silently dropped.
Register icons as premultiplied createImageBitmap(), not a raw HTMLImageElement/ImageData — straight-alpha sources make Mapbox fringe a white halo around anti-aliased edges. updateImage(name, bmp) recolours in place.
Data-driven icon-offset is silently ignored in GL JS v3. Use a constant icon-offset (it scales with icon-size) or split markers into separate symbol layers, each with its own constant anchor/offset.