@honua/react 0.1.0-beta.0 → 0.1.2-beta.0

package/map/data-to-map-bridge.js

@@ -0,0 +1,817 @@
+/**
+ * Standalone data-to-map bridge: mount any contract `Source` as a live,
+ * styled MapLibre layer set — no MapPackage, no Honua server, no
+ * app-platform import. This is the `connection.mount(target)` slice of the
+ * kernel ADR (`docs/decisions/north-star-sdk-application-kernel.md`) scoped
+ * to a caller-owned MapLibre host.
+ *
+ * The module is peer-injected and safe to import in Node/SSR/worker code:
+ * it never imports `maplibre-gl`. The host passes a duck-typed map (any
+ * MapLibre GL `Map` instance satisfies {@link DataToMapLibreMap}).
+ *
+ * @module
+ */
+import { HonuaSdkError, mergeHonuaErrorContext } from "../core/error-envelope.js";
+import { HonuaCapabilityNotSupportedError } from "../core/errors.js";
+import { createHoverHandler } from "../interactions/feature-state.js";
+import { bindPopup } from "../runtime/popups.js";
+import { buildMapLibreQueryTileSourceSpec, diagnoseQueryTileSourceSupport } from "../runtime/query-tiles.js";
+import { canonicalFeaturesToGeoJson, defaultPaint, defaultPolygonOutlinePaint, geometryKinds, layerType, mapLibreGeometryType, removeUndefined, safeId, } from "./geojson-projection.js";
+/** A stable, machine-readable bridge failure. @experimental */
+export class HonuaDataToMapBridgeError extends HonuaSdkError {
+    code;
+    detail;
+    constructor(code, message, detail, options = {}) {
+        super(DATA_TO_MAP_ERROR_CODES[code], message, {
+            ...options,
+            context: mergeHonuaErrorContext(detail, options.context),
+        });
+        this.code = code;
+        this.detail = detail;
+        this.name = "HonuaDataToMapBridgeError";
+    }
+}
+const DATA_TO_MAP_ERROR_CODES = {
+    "invalid-option": "map.data-bridge.invalid-option",
+    disposed: "map.data-bridge.disposed",
+    "source-conflict": "map.data-bridge.source-conflict",
+    "layer-conflict": "map.data-bridge.layer-conflict",
+    "map-mutation-failed": "map.data-bridge.map-mutation-failed",
+    "interaction-unsupported": "map.data-bridge.interaction-unsupported",
+    "filter-unsupported": "map.data-bridge.filter-unsupported",
+};
+const DEFAULT_MAX_GEOJSON_FEATURES = 10_000;
+const GEOMETRY_SUFFIXES = ["point", "line", "polygon", "polygon-outline"];
+/**
+ * Explain which materialization strategy {@link mountSource} would pick for
+ * a source, without touching a map. Runs the same capability checks and (when
+ * both strategies are viable) the same result-size probe.
+ *
+ * @experimental
+ */
+export async function explainDataToMapStrategy(source, options = {}) {
+    const limit = normalizedLimit(options.maxGeoJsonFeatures);
+    const reasons = [];
+    const canQuery = source.capabilities.has("query");
+    const tileDescriptor = options.queryTiles;
+    if (options.strategy === "geojson") {
+        if (!canQuery) {
+            throw new HonuaCapabilityNotSupportedError("query", source.descriptor.protocol, source.descriptor.id);
+        }
+        reasons.push(info("strategy-override", "Explicit geojson strategy override."));
+        return { strategy: "geojson", reasons };
+    }
+    if (options.strategy === "query-tiles") {
+        if (!tileDescriptor) {
+            throw new HonuaDataToMapBridgeError("invalid-option", "The query-tiles strategy requires options.queryTiles (a dynamic query-tile source descriptor).");
+        }
+        reasons.push(info("strategy-override", "Explicit query-tiles strategy override."));
+        return { strategy: "query-tiles", reasons };
+    }
+    if (options.strategy !== undefined) {
+        throw new HonuaDataToMapBridgeError("invalid-option", `Unknown strategy "${String(options.strategy)}".`, {
+            strategy: options.strategy,
+        });
+    }
+    if (!canQuery && !tileDescriptor) {
+        throw new HonuaCapabilityNotSupportedError("query", source.descriptor.protocol, source.descriptor.id);
+    }
+    if (!tileDescriptor) {
+        reasons.push(info("query-capability", "The source advertises query and no dynamic query-tile descriptor was supplied; using bounded GeoJSON materialization."));
+        if (source.capabilities.has("tiles")) {
+            reasons.push(info("tile-endpoint-missing", "The source declares the tiles capability but no options.queryTiles descriptor was supplied, so the dynamic query-tile strategy is unavailable."));
+        }
+        return { strategy: "geojson", reasons };
+    }
+    if (!canQuery) {
+        reasons.push(info("tiles-capability", "The source does not advertise query; using the dynamic query-tile strategy."));
+        return { strategy: "query-tiles", reasons };
+    }
+    // Both strategies are viable — apply the result-size heuristic. Probe with
+    // the same initial filter the mount path would apply, so a selective
+    // descriptor-level query counts what would actually be materialized.
+    const initialQuery = options.query ?? options.queryTiles?.query;
+    let count;
+    if (source.capabilities.has("queryExtent")) {
+        try {
+            const probe = await source.queryExtent({
+                ...(initialQuery ?? {}),
+                ...(options.signal ? { signal: options.signal } : {}),
+            });
+            count = probe.count;
+        }
+        catch (cause) {
+            if (options.signal?.aborted)
+                throw cause;
+            reasons.push(warning("count-probe-failed", "The result-size probe (queryExtent) failed; the count is unknown.", {
+                error: errorMessage(cause),
+            }));
+        }
+    }
+    else {
+        reasons.push(info("count-probe-unavailable", "The source does not advertise queryExtent; the result size is unknown."));
+    }
+    if (count !== undefined && count <= limit) {
+        reasons.push(info("result-size-within-limit", `${count} matching rows fit within the ${limit}-feature GeoJSON bound.`, {
+            count,
+            limit,
+        }));
+        return { strategy: "geojson", reasons, probedCount: count };
+    }
+    if (count !== undefined) {
+        reasons.push(info("result-size-exceeds-limit", `${count} matching rows exceed the ${limit}-feature GeoJSON bound; using viewport-bounded query tiles.`, { count, limit }));
+        return { strategy: "query-tiles", reasons, probedCount: count };
+    }
+    reasons.push(info("result-size-unknown", "The result size is unknown; preferring viewport-bounded query tiles over unbounded materialization."));
+    return { strategy: "query-tiles", reasons };
+}
+/**
+ * Mount a contract `Source` onto a caller-owned MapLibre map as a styled,
+ * interactive layer set and return a disposable handle that owns everything
+ * it created.
+ *
+ * The bridge selects GeoJSON materialization or the dynamic query-tile path
+ * from declared capabilities and a result-size heuristic (override with
+ * `options.strategy`), applies geometry-appropriate default styling, and can
+ * wire click popups and hover feature-state.
+ *
+ * @example
+ * ```ts
+ * import maplibregl from "maplibre-gl";
+ * import { connect } from "@honua/sdk-js";
+ * import { mountSource } from "@honua/sdk-js/map";
+ *
+ * const connection = await connect({
+ *   endpoint: FEATURE_LAYER_URL,
+ *   protocol: "auto",
+ *   authorizationScopeFingerprint: "public",
+ * });
+ * const mounted = await mountSource(map, connection.source(), {
+ *   popup: { factory: () => new maplibregl.Popup() },
+ *   hover: true,
+ *   fitBounds: true,
+ * });
+ * console.log(mounted.diagnostics.strategy, mounted.diagnostics.reasons);
+ * // Later: mounted.dispose(); // or `await using mounted = …`
+ * ```
+ *
+ * @experimental
+ */
+export async function mountSource(map, source, options = {}) {
+    validateOptions(map, options);
+    const limit = normalizedLimit(options.maxGeoJsonFeatures);
+    const lifecycle = new AbortController();
+    const signal = combineSignals([lifecycle.signal, options.signal]);
+    signal.throwIfAborted();
+    const explanation = await explainDataToMapStrategy(source, options);
+    signal.throwIfAborted();
+    const strategy = explanation.strategy;
+    const reasons = [...explanation.reasons];
+    const updates = [];
+    if (options.renderer?.kind === "cluster" && strategy !== "geojson") {
+        throw new HonuaDataToMapBridgeError("invalid-option", 'A cluster renderer requires the "geojson" strategy (MapLibre clustering is a GeoJSON-source feature); pass strategy: "geojson".', { strategy });
+    }
+    const sourceId = options.sourceId ?? `honua-${safeId(source.descriptor.id)}`;
+    const layerBase = options.layerId ?? sourceId;
+    const sourceLayer = strategy === "query-tiles"
+        ? (options.sourceLayer ?? options.queryTiles?.tilejson?.vector_layers?.[0]?.id ?? options.queryTiles?.sourceId)
+        : undefined;
+    let currentQuery = options.query ?? options.queryTiles?.query;
+    // ── Materialize the initial source spec ────────────────────────
+    let featureCount;
+    let totalCount;
+    let overflow;
+    let presentKinds;
+    let geojsonBounds;
+    let sourceSpec;
+    let currentTiles;
+    const materialize = async (query) => {
+        const callerLimit = query?.pagination?.limit;
+        const result = await source.queryAll({
+            ...(query ?? {}),
+            returnGeometry: true,
+            // MapLibre GeoJSON sources are always WGS84; respect an explicit caller override.
+            outSr: query?.outSr ?? 4326,
+            pagination: { ...(query?.pagination ?? {}), limit: Math.min(callerLimit ?? limit, limit) },
+            signal,
+        });
+        signal.throwIfAborted();
+        return result;
+    };
+    if (strategy === "geojson") {
+        const result = await materialize(currentQuery);
+        const converted = canonicalFeaturesToGeoJson(result.features, source.descriptor.schema?.primaryKey);
+        featureCount = converted.data.features.length;
+        totalCount = resolveTotalCount(result);
+        overflow = computeOverflow(result, limit, reasons);
+        presentKinds = geometryKinds(converted.data.features);
+        geojsonBounds = computeBounds(converted.data);
+        if (converted.unsupported > 0) {
+            reasons.push(warning("geometry-unsupported", `${converted.unsupported} feature geometry value(s) could not be projected and remain attribute-only.`, { unsupportedGeometryCount: converted.unsupported }));
+        }
+        if (result.degraded && result.degraded.length > 0) {
+            reasons.push(warning("source-degraded", "The source reported degraded execution semantics.", {
+                reasons: result.degraded.map((entry) => entry.reason),
+            }));
+        }
+        sourceSpec = {
+            type: "geojson",
+            data: converted.data,
+            promoteId: source.descriptor.schema?.primaryKey,
+            attribution: options.attribution ?? source.descriptor.attribution,
+            ...(options.renderer?.kind === "cluster" ? options.renderer.toMapLibreSource() : {}),
+        };
+        removeUndefined(sourceSpec);
+    }
+    else {
+        const descriptor = tileDescriptorWithQuery(requireTileDescriptor(options), currentQuery);
+        for (const diagnostic of diagnoseQueryTileSourceSupport(descriptor)) {
+            reasons.push({
+                code: "tile-support",
+                severity: diagnostic.severity === "info" ? "info" : "warning",
+                message: diagnostic.message,
+                detail: { queryTileDiagnostic: diagnostic.code },
+            });
+        }
+        const spec = buildMapLibreQueryTileSourceSpec(descriptor, { useTileJsonUrl: currentQuery === undefined });
+        currentTiles = spec.tiles ? [...spec.tiles] : undefined;
+        sourceSpec = { ...spec, attribution: options.attribution ?? spec.attribution };
+        removeUndefined(sourceSpec);
+    }
+    // ── Build the layer set ────────────────────────────────────────
+    let currentRenderer = options.renderer;
+    let layers = buildLayers(strategy, sourceId, layerBase, sourceLayer, options, currentRenderer);
+    let layerIds = layers.map((layer) => String(layer.id));
+    const interactiveIdsFor = (ids) => options.layers ? ids : ids.filter((id) => !id.endsWith("-polygon-outline") && !id.endsWith("-cluster-count"));
+    const interactiveLayerIds = interactiveIdsFor(layerIds);
+    // ── Mutate the map transactionally ─────────────────────────────
+    signal.throwIfAborted();
+    assertIdsAvailable(map, sourceId, layerIds);
+    const attempted = [];
+    try {
+        map.addSource(sourceId, sourceSpec);
+        for (const layer of layers) {
+            attempted.push(String(layer.id));
+            map.addLayer(layer, options.beforeId);
+        }
+    }
+    catch (cause) {
+        rollback(map, sourceId, attempted);
+        throw new HonuaDataToMapBridgeError("map-mutation-failed", `Failed to mount source "${sourceId}" transactionally.`, { sourceId, attemptedLayerIds: attempted }, { cause });
+    }
+    // ── Interactions ───────────────────────────────────────────────
+    const popupHandles = [];
+    const hoverHandles = [];
+    const wireInteractions = (ids) => {
+        if (options.popup) {
+            const popup = options.popup;
+            for (const layerId of ids) {
+                popupHandles.push(bindPopup(map, {
+                    binding: { sourceId, ...(popup.title !== undefined ? { title: popup.title } : {}) },
+                    layerId,
+                    popupFactory: popup.factory,
+                    render: (context) => renderPopup(popup, context.features, context.lngLat),
+                }));
+            }
+        }
+        if (options.hover) {
+            const stateKey = typeof options.hover === "object" ? (options.hover.stateKey ?? "hover") : "hover";
+            for (const layerId of ids) {
+                hoverHandles.push(createHoverHandler(map, {
+                    source: sourceId,
+                    layer: layerId,
+                    stateKey,
+                    ...(sourceLayer !== undefined ? { sourceLayer } : {}),
+                }));
+            }
+        }
+    };
+    try {
+        wireInteractions(interactiveLayerIds);
+    }
+    catch (cause) {
+        removeInteractions(popupHandles, hoverHandles);
+        rollback(map, sourceId, layerIds);
+        throw new HonuaDataToMapBridgeError("map-mutation-failed", `Failed to wire interactions for source "${sourceId}".`, { sourceId }, { cause });
+    }
+    // ── Optional camera fit ────────────────────────────────────────
+    if (options.fitBounds && typeof map.fitBounds === "function") {
+        const bounds = strategy === "geojson" ? geojsonBounds : (options.queryTiles?.bounds ?? options.queryTiles?.tilejson?.bounds);
+        if (bounds) {
+            const padding = typeof options.fitBounds === "object" ? (options.fitBounds.padding ?? 32) : 32;
+            map.fitBounds([bounds[0], bounds[1], bounds[2], bounds[3]], { padding });
+        }
+    }
+    // ── Handle ─────────────────────────────────────────────────────
+    let state = "ready";
+    let refreshTail = Promise.resolve();
+    const snapshotDiagnostics = () => Object.freeze({
+        strategy,
+        reasons: Object.freeze([...reasons]),
+        updates: Object.freeze([...updates]),
+        ...(featureCount !== undefined ? { featureCount } : {}),
+        ...(totalCount !== undefined ? { totalCount } : {}),
+        ...(overflow !== undefined ? { overflow } : {}),
+        ...(presentKinds !== undefined ? { geometryKinds: Object.freeze([...presentKinds]) } : {}),
+    });
+    const applyGeoJsonUpdate = async (query, code) => {
+        const result = await materialize(query);
+        if (state === "disposed") {
+            throw new HonuaDataToMapBridgeError("disposed", "The mounted source was disposed during an update.");
+        }
+        const converted = canonicalFeaturesToGeoJson(result.features, source.descriptor.schema?.primaryKey);
+        const handle = map.getSource(sourceId);
+        if (!handle || typeof handle.setData !== "function") {
+            throw new HonuaDataToMapBridgeError("map-mutation-failed", `Mounted source "${sourceId}" no longer exposes setData().`, { sourceId });
+        }
+        handle.setData(converted.data);
+        featureCount = converted.data.features.length;
+        totalCount = resolveTotalCount(result);
+        overflow = computeOverflow(result, limit, updates);
+        presentKinds = geometryKinds(converted.data.features);
+        updates.push(info(code, `Updated GeoJSON data in place with setData() (${featureCount} features).`));
+    };
+    const applyTileUpdate = async (query, code) => {
+        const descriptor = tileDescriptorWithQuery(requireTileDescriptor(options), query);
+        const spec = buildMapLibreQueryTileSourceSpec(descriptor, { useTileJsonUrl: false });
+        const nextTiles = spec.tiles ? [...spec.tiles] : undefined;
+        if (!nextTiles || nextTiles.length === 0) {
+            throw new HonuaDataToMapBridgeError("filter-unsupported", "The query-tile descriptor cannot produce a tile URL template for filter updates.", { sourceId });
+        }
+        if (code === "filter-applied" &&
+            currentTiles !== undefined &&
+            sameStringArray(nextTiles, currentTiles) &&
+            !sameQuery(query, currentQuery)) {
+            throw new HonuaDataToMapBridgeError("filter-unsupported", "The query-tile descriptor's fixed tile URLs cannot carry the new filter; supply an endpoint-based descriptor or use the geojson strategy.", { sourceId });
+        }
+        const handle = map.getSource(sourceId);
+        if (handle && typeof handle.setTiles === "function") {
+            handle.setTiles([...nextTiles]);
+            currentTiles = nextTiles;
+            updates.push(info(code, "Rewrote the tile URL template in place with setTiles()."));
+            return;
+        }
+        // Structural fallback for hosts without setTiles: recreate the source
+        // while keeping the layers' event bindings (they are keyed by layer id).
+        for (const layerId of [...layerIds].reverse())
+            if (map.getLayer(layerId))
+                map.removeLayer(layerId);
+        if (map.getSource(sourceId))
+            map.removeSource(sourceId);
+        const nextSpec = { ...spec, attribution: options.attribution ?? spec.attribution };
+        removeUndefined(nextSpec);
+        map.addSource(sourceId, nextSpec);
+        for (const layer of layers)
+            map.addLayer(layer, options.beforeId);
+        currentTiles = nextTiles;
+        updates.push(warning("filter-recreated-source", "The map host does not expose setTiles(); the tile source and layers were recreated in place."));
+    };
+    const clusterSourceOptionsOf = (renderer) => renderer?.kind === "cluster" ? renderer.toMapLibreSource() : undefined;
+    const applyRendererUpdate = async (next) => {
+        if (next?.kind === "cluster" && strategy !== "geojson") {
+            throw new HonuaDataToMapBridgeError("invalid-option", 'A cluster renderer requires the "geojson" strategy (MapLibre clustering is a GeoJSON-source feature).', { sourceId, strategy });
+        }
+        const nextLayers = buildLayers(strategy, sourceId, layerBase, sourceLayer, options, next);
+        const nextIds = nextLayers.map((layer) => String(layer.id));
+        const nextCluster = clusterSourceOptionsOf(next);
+        const clusterChanged = !sameJson(clusterSourceOptionsOf(currentRenderer), nextCluster);
+        const structureUnchanged = !clusterChanged &&
+            nextIds.length === layerIds.length &&
+            nextIds.every((id, index) => id === layerIds[index] && nextLayers[index].type === layers[index].type);
+        if (structureUnchanged && typeof map.setPaintProperty === "function") {
+            // Diff-update in place: no layer teardown, no source touch.
+            for (let index = 0; index < nextLayers.length; index++) {
+                const id = nextIds[index];
+                diffProperties(recordOf(layers[index].paint), recordOf(nextLayers[index].paint), (name, value) => map.setPaintProperty?.(id, name, value));
+                if (typeof map.setLayoutProperty === "function") {
+                    diffProperties(recordOf(layers[index].layout), recordOf(nextLayers[index].layout), (name, value) => map.setLayoutProperty?.(id, name, value));
+                }
+                if (typeof map.setFilter === "function" && !sameJson(layers[index].filter, nextLayers[index].filter)) {
+                    map.setFilter(id, nextLayers[index].filter);
+                }
+            }
+            layers = nextLayers;
+            currentRenderer = next;
+            updates.push(info("renderer-applied", "Updated renderer paint/layout in place without layer teardown."));
+            return;
+        }
+        // Structural path: replace the owned layers; recreate the source only
+        // when GeoJSON cluster options changed. Materialize the replacement data
+        // BEFORE any teardown so a failed or aborted query leaves the previously
+        // working layers and interactions on the map untouched.
+        const replacement = clusterChanged
+            ? await (async () => {
+                const result = await materialize(currentQuery);
+                const converted = canonicalFeaturesToGeoJson(result.features, source.descriptor.schema?.primaryKey);
+                return { result, converted };
+            })()
+            : undefined;
+        removeInteractions(popupHandles, hoverHandles);
+        for (const layerId of [...layerIds].reverse())
+            if (map.getLayer(layerId))
+                map.removeLayer(layerId);
+        if (replacement) {
+            const { result, converted } = replacement;
+            if (map.getSource(sourceId))
+                map.removeSource(sourceId);
+            const nextSpec = {
+                type: "geojson",
+                data: converted.data,
+                promoteId: source.descriptor.schema?.primaryKey,
+                attribution: options.attribution ?? source.descriptor.attribution,
+                ...(nextCluster ?? {}),
+            };
+            removeUndefined(nextSpec);
+            map.addSource(sourceId, nextSpec);
+            featureCount = converted.data.features.length;
+            totalCount = resolveTotalCount(result);
+            overflow = computeOverflow(result, limit, updates);
+            presentKinds = geometryKinds(converted.data.features);
+        }
+        for (const layer of nextLayers)
+            map.addLayer(layer, options.beforeId);
+        layers = nextLayers;
+        layerIds = nextIds;
+        currentRenderer = next;
+        wireInteractions(interactiveIdsFor(layerIds));
+        updates.push(info(clusterChanged ? "renderer-recreated-source" : "renderer-recreated-layers", clusterChanged
+            ? "Renderer swap changed GeoJSON cluster options; the source and layers were recreated."
+            : "Renderer swap changed the layer structure; the owned layers were recreated in place."));
+    };
+    const enqueue = (work) => {
+        const run = refreshTail.then(async () => {
+            if (state === "disposed") {
+                throw new HonuaDataToMapBridgeError("disposed", "Cannot update a disposed mounted source.");
+            }
+            signal.throwIfAborted();
+            await work();
+            return snapshotDiagnostics();
+        });
+        refreshTail = run.then(() => undefined, () => undefined);
+        return run;
+    };
+    const dispose = () => {
+        if (state === "disposed")
+            return;
+        state = "disposed";
+        lifecycle.abort(new DOMException("Mounted source disposed", "AbortError"));
+        const failures = [];
+        try {
+            removeInteractions(popupHandles, hoverHandles);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        for (const layerId of [...layerIds].reverse()) {
+            try {
+                if (map.getLayer(layerId))
+                    map.removeLayer(layerId);
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        try {
+            if (map.getSource(sourceId))
+                map.removeSource(sourceId);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        if (failures.length > 0) {
+            throw new HonuaDataToMapBridgeError("map-mutation-failed", `Disposal of source "${sourceId}" completed with ${failures.length} renderer failure(s).`, { sourceId, failureCount: failures.length }, { cause: failures[0] });
+        }
+    };
+    return {
+        strategy,
+        sourceId,
+        get layerIds() {
+            return [...layerIds];
+        },
+        sourceLayer,
+        get state() {
+            return state;
+        },
+        get diagnostics() {
+            return snapshotDiagnostics();
+        },
+        setFilter(query) {
+            return enqueue(async () => {
+                if (strategy === "geojson")
+                    await applyGeoJsonUpdate(query, "filter-applied");
+                else
+                    await applyTileUpdate(query, "filter-applied");
+                currentQuery = query;
+            });
+        },
+        setRenderer(renderer) {
+            return enqueue(() => applyRendererUpdate(renderer));
+        },
+        refresh() {
+            return enqueue(async () => {
+                if (strategy === "geojson")
+                    await applyGeoJsonUpdate(currentQuery, "refresh-applied");
+                else
+                    await applyTileUpdate(currentQuery, "refresh-applied");
+            });
+        },
+        dispose,
+        async [Symbol.asyncDispose]() {
+            await refreshTail;
+            dispose();
+        },
+    };
+}
+// ── Internals ────────────────────────────────────────────────────
+function validateOptions(map, options) {
+    if (options.maxGeoJsonFeatures !== undefined)
+        normalizedLimit(options.maxGeoJsonFeatures);
+    if (options.geometry !== undefined &&
+        options.geometry !== "auto" &&
+        options.geometry !== "point" &&
+        options.geometry !== "line" &&
+        options.geometry !== "polygon") {
+        throw new HonuaDataToMapBridgeError("invalid-option", `Unknown geometry "${String(options.geometry)}".`, {
+            geometry: options.geometry,
+        });
+    }
+    if (options.renderer !== undefined) {
+        if (options.layers !== undefined) {
+            throw new HonuaDataToMapBridgeError("invalid-option", "options.renderer and options.layers are mutually exclusive; renderer-derived layers own the layer set.");
+        }
+        const renderer = options.renderer;
+        if (typeof renderer.toMapLibre !== "function" || typeof renderer.kind !== "string") {
+            throw new HonuaDataToMapBridgeError("invalid-option", "options.renderer must be a renderer object from @honua/sdk-js/style (classBreaksRenderer, uniqueValueRenderer, heatmapRenderer, clusterRenderer).");
+        }
+    }
+    if (options.layers !== undefined) {
+        if (options.layers.length === 0) {
+            throw new HonuaDataToMapBridgeError("invalid-option", "options.layers must contain at least one layer.");
+        }
+        const seen = new Set();
+        for (const layer of options.layers) {
+            const id = layer.id;
+            if (typeof id !== "string" || id.length === 0 || seen.has(id)) {
+                throw new HonuaDataToMapBridgeError("invalid-option", "Every options.layers entry needs a unique string id.", {
+                    layerId: id,
+                });
+            }
+            seen.add(id);
+        }
+    }
+    if (options.popup && (typeof map.on !== "function" || typeof map.off !== "function")) {
+        throw new HonuaDataToMapBridgeError("interaction-unsupported", "Popups require a map with on()/off() event methods.");
+    }
+    if (options.hover &&
+        (typeof map.on !== "function" || typeof map.off !== "function" || typeof map.setFeatureState !== "function")) {
+        throw new HonuaDataToMapBridgeError("interaction-unsupported", "Hover feature-state requires a map with on()/off() and setFeatureState() methods.");
+    }
+}
+function normalizedLimit(value) {
+    if (value === undefined)
+        return DEFAULT_MAX_GEOJSON_FEATURES;
+    if (!Number.isInteger(value) || value < 1) {
+        throw new HonuaDataToMapBridgeError("invalid-option", "maxGeoJsonFeatures must be a positive integer.", {
+            maxGeoJsonFeatures: value,
+        });
+    }
+    return value;
+}
+function requireTileDescriptor(options) {
+    const descriptor = options.queryTiles;
+    if (!descriptor) {
+        throw new HonuaDataToMapBridgeError("invalid-option", "The query-tiles strategy requires options.queryTiles (a dynamic query-tile source descriptor).");
+    }
+    return descriptor;
+}
+function tileDescriptorWithQuery(descriptor, query) {
+    if (query !== undefined)
+        return { ...descriptor, query: { ...query } };
+    // `setFilter(undefined)` clears the mounted filter: strip a baked
+    // descriptor-level query too, so the rebuilt tile URL is unfiltered.
+    if (descriptor.query === undefined)
+        return descriptor;
+    const { query: _cleared, ...rest } = descriptor;
+    return rest;
+}
+function buildLayers(strategy, sourceId, layerBase, sourceLayer, options, renderer) {
+    if (options.layers) {
+        return options.layers.map((layer) => Object.freeze({
+            source: sourceId,
+            ...(strategy === "query-tiles" && sourceLayer !== undefined && layer["source-layer"] === undefined
+                ? { "source-layer": sourceLayer }
+                : {}),
+            ...layer,
+        }));
+    }
+    if (renderer?.kind === "cluster") {
+        return renderer.toMapLibre("point").map((fragment) => Object.freeze({
+            id: `${layerBase}-${fragment.role}`,
+            type: fragment.type,
+            source: sourceId,
+            ...(fragment.filter !== undefined ? { filter: fragment.filter } : {}),
+            paint: { ...fragment.paint },
+            ...(Object.keys(fragment.layout).length > 0 ? { layout: { ...fragment.layout } } : {}),
+            metadata: { "honua:mount": "data-to-map-bridge", "honua:strategy": strategy, "honua:renderer": renderer.kind },
+        }));
+    }
+    if (renderer?.kind === "heatmap") {
+        const [fragment] = renderer.toMapLibre("point");
+        return [
+            Object.freeze({
+                id: `${layerBase}-heatmap`,
+                type: fragment.type,
+                source: sourceId,
+                ...(sourceLayer !== undefined ? { "source-layer": sourceLayer } : {}),
+                filter: ["==", ["geometry-type"], "Point"],
+                paint: { ...fragment.paint },
+                ...(Object.keys(fragment.layout).length > 0 ? { layout: { ...fragment.layout } } : {}),
+                metadata: { "honua:mount": "data-to-map-bridge", "honua:strategy": strategy, "honua:renderer": renderer.kind },
+            }),
+        ];
+    }
+    const requested = options.geometry === undefined || options.geometry === "auto" ? undefined : options.geometry;
+    const kinds = requested ? [requested] : ["point", "line", "polygon"];
+    const layers = [];
+    for (const kind of kinds) {
+        const fragment = renderer ? renderer.toMapLibre(kind)[0] : undefined;
+        const rendererLayout = fragment && Object.keys(fragment.layout).length > 0 ? fragment.layout : undefined;
+        layers.push(layerSpec(strategy, sourceId, `${layerBase}-${kind}`, layerType(kind), kind, sourceLayer, {
+            ...defaultPaint(kind),
+            ...(fragment?.paint ?? {}),
+            ...(options.paint?.[kind] ?? {}),
+        }, rendererLayout || options.layout?.[kind]
+            ? { ...(rendererLayout ?? {}), ...(options.layout?.[kind] ?? {}) }
+            : undefined));
+        if (kind === "polygon") {
+            layers.push(layerSpec(strategy, sourceId, `${layerBase}-polygon-outline`, "line", "polygon", sourceLayer, {
+                ...defaultPolygonOutlinePaint(),
+                ...(options.paint?.polygonOutline ?? {}),
+            }, options.layout?.polygonOutline));
+        }
+    }
+    return layers.map((layer) => Object.freeze(layer));
+}
+function layerSpec(strategy, sourceId, id, type, kind, sourceLayer, paint, layout) {
+    return {
+        id,
+        type,
+        source: sourceId,
+        ...(sourceLayer !== undefined ? { "source-layer": sourceLayer } : {}),
+        filter: ["==", ["geometry-type"], mapLibreGeometryType(kind)],
+        paint,
+        ...(layout ? { layout: { ...layout } } : {}),
+        metadata: { "honua:mount": "data-to-map-bridge", "honua:strategy": strategy },
+    };
+}
+function assertIdsAvailable(map, sourceId, layerIds) {
+    if (map.getSource(sourceId)) {
+        throw new HonuaDataToMapBridgeError("source-conflict", `MapLibre source "${sourceId}" already exists.`, {
+            sourceId,
+        });
+    }
+    for (const layerId of layerIds) {
+        if (map.getLayer(layerId)) {
+            throw new HonuaDataToMapBridgeError("layer-conflict", `MapLibre layer "${layerId}" already exists.`, {
+                layerId,
+            });
+        }
+    }
+}
+function rollback(map, sourceId, layerIds) {
+    for (const layerId of [...layerIds].reverse()) {
+        try {
+            if (map.getLayer(layerId))
+                map.removeLayer(layerId);
+        }
+        catch {
+            /* best-effort rollback */
+        }
+    }
+    try {
+        if (map.getSource(sourceId))
+            map.removeSource(sourceId);
+    }
+    catch {
+        /* best-effort rollback */
+    }
+}
+function removeInteractions(popupHandles, hoverHandles) {
+    for (const handle of popupHandles.splice(0))
+        handle.remove();
+    for (const handle of hoverHandles.splice(0))
+        handle.remove();
+}
+function renderPopup(options, features, lngLat) {
+    if (options.render)
+        return options.render({ features, lngLat });
+    const doc = typeof document !== "undefined" ? document : undefined;
+    const feature = features[0];
+    if (!doc || !feature?.properties)
+        return undefined;
+    const root = doc.createElement("div");
+    if (options.title) {
+        const title = doc.createElement("h3");
+        title.textContent = options.title;
+        root.appendChild(title);
+    }
+    const fields = options.fields
+        ? options.fields.filter((field) => Object.hasOwn(feature.properties ?? {}, field))
+        : Object.keys(feature.properties);
+    const dl = doc.createElement("dl");
+    for (const field of fields) {
+        const dt = doc.createElement("dt");
+        dt.textContent = field;
+        const dd = doc.createElement("dd");
+        dd.textContent = String(feature.properties[field]);
+        dl.appendChild(dt);
+        dl.appendChild(dd);
+    }
+    root.appendChild(dl);
+    return root;
+}
+function resolveTotalCount(result) {
+    // Some adapters report totalCount as the returned page size; drop it when
+    // the result was truncated and the count carries no extra information.
+    if (result.totalCount !== undefined && (result.totalCount > result.features.length || !result.exceededTransferLimit))
+        return result.totalCount;
+    return result.exceededTransferLimit ? undefined : (result.totalCount ?? result.features.length);
+}
+function computeOverflow(result, limit, sink) {
+    if (!result.exceededTransferLimit)
+        return undefined;
+    const overflow = Object.freeze({
+        truncated: true,
+        renderedFeatureCount: result.features.length,
+        limit,
+        ...(result.totalCount !== undefined && result.totalCount > result.features.length
+            ? { totalCount: result.totalCount }
+            : {}),
+    });
+    sink.push(warning("overflow-truncated", `GeoJSON materialization was truncated at ${result.features.length} of the matching rows (limit ${limit}); raise maxGeoJsonFeatures or use the query-tiles strategy.`, { renderedFeatureCount: result.features.length, limit }));
+    return overflow;
+}
+function computeBounds(data) {
+    let xmin = Number.POSITIVE_INFINITY;
+    let ymin = Number.POSITIVE_INFINITY;
+    let xmax = Number.NEGATIVE_INFINITY;
+    let ymax = Number.NEGATIVE_INFINITY;
+    const visit = (coordinates) => {
+        if (!Array.isArray(coordinates))
+            return;
+        if (coordinates.length >= 2 && typeof coordinates[0] === "number" && typeof coordinates[1] === "number") {
+            const [x, y] = coordinates;
+            if (Number.isFinite(x) && Number.isFinite(y)) {
+                xmin = Math.min(xmin, x);
+                ymin = Math.min(ymin, y);
+                xmax = Math.max(xmax, x);
+                ymax = Math.max(ymax, y);
+            }
+            return;
+        }
+        for (const entry of coordinates)
+            visit(entry);
+    };
+    for (const feature of data.features)
+        visit(feature.geometry?.coordinates);
+    if (!Number.isFinite(xmin) || !Number.isFinite(ymin) || !Number.isFinite(xmax) || !Number.isFinite(ymax)) {
+        return undefined;
+    }
+    return [xmin, ymin, xmax, ymax];
+}
+function sameStringArray(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function sameQuery(left, right) {
+    return sameJson(left, right);
+}
+function sameJson(left, right) {
+    return JSON.stringify(left ?? null) === JSON.stringify(right ?? null);
+}
+function recordOf(value) {
+    return value && typeof value === "object" ? value : {};
+}
+/** Apply added/changed keys and unset removed keys through a MapLibre setter. */
+function diffProperties(previous, next, set) {
+    for (const [key, value] of Object.entries(next)) {
+        if (!sameJson(previous[key], value))
+            set(key, value);
+    }
+    for (const key of Object.keys(previous)) {
+        if (!(key in next))
+            set(key, undefined);
+    }
+}
+function combineSignals(signals) {
+    const available = signals.filter((signal) => signal !== undefined);
+    return available.length === 1 ? available[0] : AbortSignal.any(available);
+}
+function info(code, message, detail) {
+    return Object.freeze({ code, severity: "info", message, ...(detail ? { detail } : {}) });
+}
+function warning(code, message, detail) {
+    return Object.freeze({ code, severity: "warning", message, ...(detail ? { detail } : {}) });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}