add_hex_tile_layer: source-layer hardcoded to 'hex' — breaks against real mcp-data-server v0.3.0 tiles

[cboettig]

What's failing

Browser smoke test of PR #170 (feat/add-hex-tile-layer) against dev mcp-data-server: the agent completes all three steps the user asked for (register → min/max → add layer), the tile endpoint serves valid MVT, but the hex layer never renders.

Test prompt (padus.nrp-nautilus.io, 2026-04-18T19:13Z):

For Arizona fee lands, register its hex tiles, query the min/max of some numeric column, then add it as a hex layer on the map

The agent ended with a success message ("Hex Layer Added to Map ✅ … Layer ID: hex-8fc3f558abc296d1") but the map was blank.

Root cause (client side)

app/map-manager.js:528,543 hardcodes:

'source-layer': 'hex',
// ...
sourceLayer: 'hex',

The actual MVT emitted by mcp-data-server v0.3.0 names the layer "layer" (raw decode: \x1a\x05layer...). MapLibre silently draws nothing when source-layer doesn't match — there's no console warning.

Companion upstream issues

• register_hex_tiles: MVT source-layer name not exposed in return value (default is 'layer', clients expect 'hex') mcp-data-server#77 — register_hex_tiles return value needs to expose layer_name so clients don't have to hardcode.
• register_hex_tiles: agg='COUNT' not embedded as MVT property — no colorable value column mcp-data-server#78 — agg="COUNT" doesn't embed a count column in the MVT, so even after fixing the source-layer mismatch, ['get', 'feature_count'] → null → transparent.

Proposed fix (once mcp-data-server#77 lands)

1. add_hex_tile_layer tool accepts a layer_name argument (from register_hex_tiles's return value) and the tool description should tell the model to pass it through.
2. MapManager.addHexTileLayer(opts) takes layerName and uses it for source-layer instead of the hardcoded 'hex'.
3. Update tests/map-manager.hex.test.js to exercise a non-'hex' layer name.

Short-term workaround

While mcp-data-server#77 is in flight, pin source-layer to whatever the server currently emits ('layer'). This unblocks browser testing but is fragile — it should not ship as the long-term fix.

Verification

• Against a live mcp-data-server emitting MVT layer name X, calling add_hex_tile_layer(..., layer_name: "X") renders visible colored hexes over the requested bounds.
• Test that the tool still works when register_hex_tiles and add_hex_tile_layer are called in sequence in a real browser session.
• Existing 17 unit tests (npm test) continue to pass.

Log evidence

• Session: https://padus.nrp-nautilus.io, user_question "For Arizona fee lands, register its hex tiles...", 2026-04-18T19:13:56–19:15:30Z (padus logs)
• register_hex_tiles returned value_columns: ["h0"], hash: "8fc3f558abc296d1"
• add_hex_tile_layer called with value_column: "h0", value_range: [1,196]
• Tile fetched successfully (200, 1030 B at z=10), layer name = "layer", property keys = {h0, res}

[cboettig]

Additional scope: paint expression must scale with H3 resolution

register_hex_tiles rolls up across multiple resolutions (e.g. res 2–8 for finest_res=8, min_res=2) and the MVT embeds a res property per feature. The value being painted (e.g. a COUNT rollup) has a wildly different magnitude at each level — roughly 7× per resolution step — so a single client-side [min, max] will saturate or wash out most zooms.

buildFillColorExpression currently takes one value_range and applies it uniformly. Once boettiger-lab/mcp-data-server#78 is fixed (per-resolution value stats returned from register_hex_tiles), this helper needs to:

• Accept per-resolution ranges: value_range_by_res: { "2": [1, 52000], "3": [1, 7400], ..., "8": [1, 196] }
• Build a match on ['get', 'res'] that switches the interpolate domain based on which resolution the feature is at.

OR, if mcp-data-server adopts the density-normalization alternative instead, buildFillColorExpression stays as-is and the value_column points at a resolution-invariant count_per_km2 (or similar).

Either choice is driven by the server-side decision in mcp-data-server#78.