Add add_h3t_source() for tiled H3J (h3t) data

[bbest]

Summary

Adds add_h3t_source() — an R wrapper for the h3tiles:// MapLibre protocol that's already bundled in inst/htmlwidgets/lib/h3j-h3t/h3j_h3t.js but previously had no R entry point. This lets users drive H3 hex layers from a tiled HTTP endpoint (one request per viewport) instead of loading a single monolithic H3J file up front.

While wiring this up I also hit five bugs in the bundled h3j-h3t JS that blocked it from working on MapLibre v3+/v4/v5 and from supporting multiple sources per page. Those are now fixed in the bundled copy (v0.9.7) and upstreamed in INSPIDE/h3j-h3t#8 — happy to swap the bundled file for INSPIDE's release once that PR lands.

Motivation

add_h3j_source() is great when your whole dataset fits in a single JSON file, but it breaks down once you have hundreds of thousands of cells or want to filter on the fly. The h3t tile protocol solves both — the browser only fetches cells inside the current viewport/zoom, and the HTTP layer becomes a natural cache key.

Representative use case (a Shiny app doing species × environment compare): preloading all 10 H3 resolutions of a 500 k-row DuckDB aggregate was taking ~10 s per session and couldn't cache user filter changes. Moving to add_h3t_source() dropped initial load to <2 s and made every filter change a server-side operation only.

What's included

R / widget wiring

• add_h3t_source(map, id, tiles, sourcelayer, geometry_type, minzoom, maxzoom, promote_id, debug) in R/h3j-h3t.R. Supports both static maps and maplibre_proxy updates.
• x.h3t_sources init handler in inst/htmlwidgets/maplibregl.js and inst/htmlwidgets/maplibregl_compare.js.
• New add_h3t_sources proxy-message handler. Drive-by: also adds the missing add_h3j_sources proxy handler — add_h3j_source()'s proxy branch previously had no JS counterpart.
• man/add_h3t_source.Rd with a runnable example.
• Small defensive fixes in maplibregl_compare.js's layers_control: pre-check with map.getLayer(id) before calling getLayoutProperty / setLayoutProperty, since the latter emits an error event (not a throw) when the layer isn't on that map. In a compare widget a single layers_control can reference ids from both sides, so this check is necessary to avoid console noise like Cannot get style of non-existing layer "x".

Bundled h3j-h3t JS: 0.9.2 → 0.9.7

Upstreamed in INSPIDE/h3j-h3t#8. Summary:

version	fix	symptom
0.9.3	empty tiles return ArrayBuffer(0) instead of null	Cannot read properties of undefined (reading 'data') on ocean tiles of coastal data
0.9.4	support MapLibre v3+/v4 Promise protocol API (in addition to v2 callback)	e is not a function on every tile request
0.9.5	return ArrayBuffer instead of Uint8Array	MapLibre v5 rejects the Uint8Array vt-pbf returns
0.9.6	parse z/x/y with a regex anchored on .h3t$ rather than splitting on / and .	Any URL with a query string containing a dot (e.g. ?release=v2026.04.08) parsed NaN as x, every tile empty
0.9.7	mint a unique protocol scheme per source (h3t1://, h3t2:// …) instead of the fixed h3tiles://	map.addProtocol('h3tiles', handler) is a global registry — the second call overwrote the first, so two sources on one map (or one source on each side of a compare widget) clobbered each other's sourcelayer

Net: add_h3t_source() now works cleanly against MapLibre 3.6.x – 5.22.x, with multiple sources on a single page and on both sides of compare().

R CMD check passes with 0 errors / 0 warnings / 0 notes (with _R_CHECK_FORCE_SUGGESTS_=false to skip the optional mapboxapi dep).

Reproducible demo

A companion tile server lives at CalCOFI/api-h3t (MIT, standalone, pairs with any DuckDB file that has H3 cells). To reproduce:

# start an h3t tile server against your DuckDB
git clone https://github.com/CalCOFI/api-h3t.git && cd api-h3t
docker build -t api-h3t .
docker run --rm -p 8889:8889 \
  -e DUCKDB_PATH=/data/your.duckdb \
  -v "/path/to/dir:/data:ro" \
  api-h3t

# drive it from mapgl
library(mapgl)
library(base64enc)

sql <- "SELECT hex_h3res{{res}} AS cell_id, COUNT(*) AS value, COUNT(*) AS n
          FROM your_table GROUP BY 1"
q   <- base64encode(charToRaw(sql)) |>
         chartr("+/", "-_", x = _) |> sub("=+$", "", x = _)

maplibre(center = c(-119, 34), zoom = 5) |>
  add_h3t_source(
    id    = "cells",
    tiles = sprintf("h3tiles://localhost:8889/h3t/{z}/{x}/{y}.h3t?q=%s", q)
  ) |>
  add_fill_layer(
    id           = "cells",
    source       = "cells",
    source_layer = "cells",
    fill_color   = interpolate(column = "value",
                               values = c(1, 100),
                               stops  = c("#ffffcc", "#e31a1c")),
    fill_opacity = 0.7
  )

The {{res}} placeholder is a convention of the example server — add_h3t_source() itself is source-agnostic and will work with any endpoint that returns h3j JSON.

Scope / non-goals

• Mapbox parity: not touched. mapboxgl.js has no addH3TSource symbol today (and no addH3JSource either). Happy to mirror if you'd like it in this PR.
• Proxy setter for updating tile URLs after init: not included; re-calling add_h3t_source() on a maplibre_proxy adds a new source, it doesn't mutate an existing one. Worth a separate PR once a clear API emerges.

Test plan

• R CMD check --no-manual → 0E / 0W / 0N
• Interactive smoke: maplibre() |> add_h3t_source(...) |> add_fill_layer(...) renders; tiles requested on pan/zoom; MVT conversion happens client-side
• Shiny proxy: maplibre_proxy("map") |> add_h3t_source(...) triggers add_h3t_sources message; source registers
• Compare widget: compare(m1, m2) with h3t sources on both sides — both load and do not clobber each other (0.9.7 fix)
• Exercised against two real datasets (~3 k cells @ res 5, ~500 k underlying rows) on MapLibre 5.22.x

🤖 Generated with Claude Code

[cboettig]

Very nice!

[bbest]

Standby, this is not yet functional.

PS @cboettig this was inspired by your addition of add_h3j_source() #68, which I would not even attempt except for the superhuman powers of Claude to facilitate.

[bbest]

All is working now, but hope to update with an easier reproducible example in the next couple of weeks.

This update also depends on INSPIDE/h3j-h3t#8, and that JS library has not been updated in 4 years.

Here's the (somewhat complicated) code of where it's working using mapgl::compare() comparing biological sampling on left with environmental parameters on the right:

• live Shiny app
  app.calcofi.io/int
  
• source code
  github.com/CalCOFI/int-app