Layer Catalog

@openweather/maps-core ships a hardcoded catalog (DEFAULT_LAYER_CATALOG) of LayerMetadata records. Each entry declares everything a provider/renderer needs to resolve and paint it — path/format, color ramp, value scale, cadence, models, contour config, crop mask, and entitlement key — so adding a layer is a data change in that file, not a code change.

There is no remote /maps/metadata fetch. The engine uses the bundled catalog (or an availableLayers override passed to createCoreMapController).

Available layers

These are the layers the simple UI kit exposes today (the layer panel's POPULAR_CATEGORIES). Codes match DEFAULT_LAYER_CATALOG.

Group	Codes	Notes
Radar	radar	Time-segmented nowcast (past) / forecast (future); see below
Temperature / moisture	temperature, dew_point, relative_humidity
Soil	soilMoisture, soil_temperature_0_10, soil_temperature_10_40	Land-cropped
Precipitation	precipitation, precipitation_intensity, precipitation_convective, precipitation_rain, precipitation_snow, snow_depth
Wind	windSpeed	Animated particle overlay
Pressure	pressure	Isobar contours on by default
Clouds	clouds
Marine	wave_height, swell, sea_temperature	Water-cropped. wave_height / swell are status: 'preview' (height colorized, not direction)

cyclones is an overlay (toggleCycloneOverlay), not a layer-panel entry — the catalog still holds its GeoJSON endpoint. satellite exists in the catalog but isn't part of any popular category.

LayerMetadata fields

Each entry may declare:

Field	Purpose
providerKind	'tile' | 'raster' | 'geojson' — which provider resolves this layer
path / format / baseUrl	Tile URL assembly
colorRamp	Up to 100 threshold stops (hex/rgba), interpolated in-shader
interpolation	Auto, Nearest, Bilinear, Bicubic, Lanczos, Smoothstep, Rbf
valueScale	Linear, Gamma, Log
valueRange / legendRange	Physical value bounds for colorization vs. legend display
updateCadenceMinutes / timeAlignment	How the timeline snaps dates for this layer
probePolicy	HEAD-probe walk-back policy for missing frames (offset, step, max steps)
models	Alternate data sources for one code (e.g. radar's nowcast / forecast)
tilePyramid	Multi-resolution tile grids for zoom-dependent detail
contours	Isoline spacing, label scale, extrema flags
cropMask	land / water cover so soil layers hide oceans and marine layers hide continents
rasterParams	Server-side render params for raster providers
entitlementKey	Which subscription unlocks this layer if it 403s
displayScale / displayDigits / displayUnits	Point-query / legend display formatting (e.g. Pa → hPa)
description / status	status is 'preview' | 'planned' | 'experimental', omitted when stable — currently set on wave_height/swell only

Override the catalog at controller construction with availableLayers if you need a subset or custom entries. mergeCatalogWithMetadata is still exported for composing local catalogs; the engine does not call a remote metadata API.

Radar tile pyramid example

Radar's nowcast model (observed):

Level	Grid	Map zoom gate
0	1×1	always
1	4×4	≥ RADAR_TILE_MIN_ZOOM_L1 (3)
2	16×16	≥ RADAR_TILE_MIN_ZOOM_L2 (6)

Its forecast model shares levels 0-1 exactly, but level 2 is a coarser 8×8 grid at the same zoom gates — same 2048px tiles, half the linear resolution at the deepest level only.

MultiTileScalarManager (in @openweather/maps-maplibre) picks the right level for the current zoom, fetches the grid, and stitches it into one canvas for ScalarFlow — see Architecture — Multi-tile assembly.

Time-segmented layers (timeSegments)

A layer can route each timeline frame to a different models entry by the frame's position relative to "now" — radar's nowcast/forecast split is the only one in the default catalog, but the mechanism (LayerMetadata.timeSegments, timelineWindow, and the AUTO_MODEL_ID sentinel on defaultModelId) is general. See resolveSegmentModelId in @openweather/maps-core's data/layer-model.ts.