Data-to-map bridge (mountSource)

Status: @experimental — the surface ships on the stable /map entrypoint but the option and diagnostics shapes may still change in minor releases.

mountSource(map, source, options) from @honua/sdk-js/map turns any contract Source into a live, styled MapLibre layer set — no MapPackage, no Honua server, no app-platform import. It is the standalone slice of the kernel ADR's connection.mount(target) contract (docs/decisions/north-star-sdk-application-kernel.md): the bridge borrows a caller-owned map, mutates it transactionally, and returns one handle that owns every source, layer, and event listener it created.

The module never imports maplibre-gl. The map parameter is duck-typed (DataToMapLibreMap); any MapLibre GL Map instance works, and so do the test doubles used by the SDK's own suites.

import maplibregl from "maplibre-gl";
import { connect } from "@honua/sdk-js";
import { mountSource } from "@honua/sdk-js/map";

const map = new maplibregl.Map({ container: "map", style: BASEMAP_STYLE_URL, center: [-98, 39], zoom: 3 });
await map.once("load");
const data = await connect({ endpoint: FEATURE_LAYER_URL, protocol: "auto", authorizationScopeFingerprint: "public" });
const mounted = await mountSource(map, data.source(), {
  popup: { factory: () => new maplibregl.Popup(), fields: ["NAME"] },
  hover: true,
  fitBounds: true,
});

The runnable version of this workflow (fixture and live lanes) is examples/endpoint-to-map/.

Strategy selection

The bridge materializes data one of two ways:

Selection is deterministic and recorded on the handle:

1. options.strategy — explicit override, validated against capabilities.
2. No options.queryTiles descriptor → "geojson" (the source must advertise query). A declared tiles capability without a descriptor is reported as a tile-endpoint-missing reason, not silently upgraded.
3. options.queryTiles present but no query capability → "query-tiles".
4. Both viable → result-size heuristic: when the source advertises queryExtent, the bridge probes the matching row count. Counts within maxGeoJsonFeatures (default 10 000) choose "geojson"; larger or unknown counts choose "query-tiles" (bounded tile requests over unbounded materialization).

explainDataToMapStrategy(source, options) runs the same logic without touching a map, mirroring the query planner's explain-before-execute vocabulary:

import { explainDataToMapStrategy } from "@honua/sdk-js/map";

const explanation = await explainDataToMapStrategy(source, { queryTiles });
console.log(explanation.strategy);            // "geojson" | "query-tiles"
console.log(explanation.probedCount);         // row count when the probe ran
for (const reason of explanation.reasons) console.log(reason.code, reason.message);

Diagnostics on the handle

mounted.diagnostics is the explain surface required by the bridge contract (REQ-002). It carries:

• strategy and reasons[] — why the strategy was chosen (strategy-override, result-size-within-limit, count-probe-unavailable, …).
• featureCount, totalCount, geometryKinds — current GeoJSON materialization state.
• overflow — pagination-truncation report (below).
• updates[] — lifecycle events appended by setFilter / refresh (filter-applied, filter-recreated-source, refresh-applied).

Limits and overflow

GeoJSON materialization is always bounded by maxGeoJsonFeatures. When the source reports more matching rows than were materialized, the handle reports it instead of pretending the map is complete:

if (mounted.diagnostics.overflow) {
  const { renderedFeatureCount, totalCount, limit } = mounted.diagnostics.overflow;
  // e.g. "Showing 10000 of 250000 rows" — raise maxGeoJsonFeatures,
  // narrow options.query, or supply a queryTiles descriptor.
}

Default styling

Without overrides the bridge installs a stable geometry matrix so filter changes can move between geometry kinds without structural layer churn:

• <layerId>-point — circle layer (filtered to Point)
• <layerId>-line — line layer (filtered to LineString)
• <layerId>-polygon — fill layer (filtered to Polygon)
• <layerId>-polygon-outline — line layer over the polygon fill

Overrides, from lightest to heaviest:

await mountSource(map, source, {
  geometry: "polygon",                                  // restrict to one kind (fill + outline)
  paint: {
    polygon: { "fill-color": "#123456" },               // merged over the defaults
    polygonOutline: { "line-width": 3 },
  },
  layout: { point: { visibility: "visible" } },
});

await mountSource(map, source, {
  layers: [                                             // full control: bridge adds them verbatim
    { id: "heat", type: "heatmap", paint: { "heatmap-radius": 12 } },
  ],
});

The GeoJSON source sets promoteId from schema.primaryKey so feature-state (hover, selection) works out of the box, and requests WGS84 output (outSr: 4326) unless the caller's query specifies otherwise.

Interactions

await mountSource(map, source, {
  popup: {
    factory: () => new maplibregl.Popup({ closeButton: true }),
    fields: ["NAME", "STATUS"],                    // or a formatter:
    // render: ({ features }) => `<b>${features[0]?.properties?.NAME}</b>`,
    title: "Parcel",
  },
  hover: true,                                     // or { stateKey: "highlight" }
});

• Popup — binds click on each interactive layer through the runtime's popup primitives. fields restricts the default definition-list renderer; render replaces it entirely (return undefined to suppress a popup).
• Hover — toggles a boolean feature-state key through the interactions layer (createHoverHandler). Pair it with a paint expression such as ["case", ["boolean", ["feature-state", "hover"], false], 1, 0.6].

Both require the corresponding map methods (on/off, setFeatureState); the bridge throws a typed interaction-unsupported error rather than degrading silently.

Filter updates and refresh

setFilter(query) replaces the mounted filter and diff-updates rather than tearing down:

• GeoJSON — re-runs the bounded query and applies it through source.setData(); layers, listeners, and camera are untouched.
• Query-tiles — rewrites the tile URL template (the descriptor's query) and applies it through source.setTiles(). Hosts without setTiles get an in-place source recreation (reported as a filter-recreated-source warning). Descriptors with fixed tile URLs that cannot carry a query throw a typed filter-unsupported error instead of silently rendering stale data.

refresh() re-executes the current filter through the same paths. Updates are serialized: concurrent calls run in order, never interleaved.

await mounted.setFilter({ where: "STATUS = 'ACTIVE'" });
await mounted.refresh();
await mounted.setFilter(undefined);   // clear

Disposal

The handle owns every MapLibre resource it created and follows the kernel resource-ownership contract (REQ-004):

• dispose() removes popup bindings, hover handlers, layers (reverse order), and the source, then aborts any in-flight query work. It is idempotent — a second call (React StrictMode double-invoke, finally blocks) is a silent no-op.
• Symbol.asyncDispose awaits in-flight updates before disposing, so await using works end-to-end:

{
  await using mounted = await mountSource(map, source);
  // … the mount is removed when the block exits
}

The bridge never touches resources it did not create: the map itself, the basemap style, and other sources/layers stay caller-owned.

Option reference

Related surfaces

• Accepted-plan (fingerprinted) mounting and the automatic strategy planner: docs/maplibre-runtime.md — mountSourceToMapLibre / explainAutomaticSourceToMapLibre on the same /map entrypoint. Use those when you need plan review, provenance, and freshness policy; use mountSource when you want the ten-line path.
• Dynamic query-tile descriptors, TileJSON, and the tile request controller: @honua/sdk-js/runtime (buildMapLibreQueryTileSourceSpec, QueryTileRequestController).
• Feature-state and selection primitives: @honua/sdk-js/interactions.