@honua/react 0.0.20-alpha.0

package/interactions/share-state.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shareable serialization helpers for map/table/detail interaction state.
+ *
+ * The encoded query string is intended for URLs and bookmarks. It carries the
+ * query projection and selection but leaves state ownership with
+ * `ExplorationContext`.
+ *
+ * @module
+ */
+import type { LinkedViewQueryProjection } from "../exploration/selectors.js";
+import type { FeatureSelectionTarget } from "../exploration/types.js";
+export type ShareableInteractionQueryState = Partial<LinkedViewQueryProjection> & {
+    readonly selection?: ReadonlyArray<FeatureSelectionTarget>;
+};
+export interface ShareableInteractionQueryParams {
+    readonly filters: string;
+    readonly spatialFilter: string;
+    readonly extent: string;
+    readonly orderBy: string;
+    readonly pagination: string;
+    readonly outFields: string;
+    readonly grouping: string;
+    readonly aggregation: string;
+    readonly selection: string;
+}
+/** Encode selection targets as a stable JSON value suitable for a URL param. */
+export declare function serializeSelection(selection: ReadonlyArray<FeatureSelectionTarget>): string;
+/** Decode a selection value produced by {@link serializeSelection}. */
+export declare function parseSelection(value: string | null | undefined): FeatureSelectionTarget[];
+/** Encode query projection state into URL query parameters. */
+export declare function serializeInteractionQueryState(state: ShareableInteractionQueryState): string;
+/** Decode URL query parameters produced by {@link serializeInteractionQueryState}. */
+export declare function parseInteractionQueryState(search: string | URLSearchParams): ShareableInteractionQueryState;
+/** Return the query parameter names used by the shareable serializer. */
+export declare function interactionQueryParamNames(): ShareableInteractionQueryParams;
+//# sourceMappingURL=share-state.d.ts.map

package/interactions/share-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"share-state.d.ts","sourceRoot":"","sources":["../../../src/interactions/share-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAC7E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAEtE,MAAM,MAAM,8BAA8B,GAAG,OAAO,CAAC,yBAAyB,CAAC,GAAG;IAChF,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAC;CAC5D,CAAC;AAEF,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAcD,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,aAAa,CAAC,sBAAsB,CAAC,GAAG,MAAM,CAE3F;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,sBAAsB,EAAE,CAIzF;AAED,+DAA+D;AAC/D,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,8BAA8B,GAAG,MAAM,CAY5F;AAED,sFAAsF;AACtF,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,8BAA8B,CAc3G;AAED,yEAAyE;AACzE,wBAAgB,0BAA0B,IAAI,+BAA+B,CAE5E"}

package/interactions/share-state.js

@@ -0,0 +1,123 @@
+/**
+ * Shareable serialization helpers for map/table/detail interaction state.
+ *
+ * The encoded query string is intended for URLs and bookmarks. It carries the
+ * query projection and selection but leaves state ownership with
+ * `ExplorationContext`.
+ *
+ * @module
+ */
+const PARAMS = {
+    filters: "f",
+    spatialFilter: "sf",
+    extent: "ext",
+    orderBy: "sort",
+    pagination: "page",
+    outFields: "fields",
+    grouping: "group",
+    aggregation: "agg",
+    selection: "sel",
+};
+/** Encode selection targets as a stable JSON value suitable for a URL param. */
+export function serializeSelection(selection) {
+    return stableStringify(selection);
+}
+/** Decode a selection value produced by {@link serializeSelection}. */
+export function parseSelection(value) {
+    if (!value)
+        return [];
+    const parsed = parseJson(value);
+    return Array.isArray(parsed) ? parsed.filter(isSelectionTarget) : [];
+}
+/** Encode query projection state into URL query parameters. */
+export function serializeInteractionQueryState(state) {
+    const params = new URLSearchParams();
+    setJsonParam(params, PARAMS.filters, emptyObjectToUndefined(state.filters));
+    setJsonParam(params, PARAMS.spatialFilter, state.spatialFilter);
+    setJsonParam(params, PARAMS.extent, state.extent);
+    setJsonParam(params, PARAMS.orderBy, emptyArrayToUndefined(state.orderBy));
+    setJsonParam(params, PARAMS.pagination, emptyObjectToUndefined(state.pagination));
+    setJsonParam(params, PARAMS.outFields, emptyArrayToUndefined(state.outFields));
+    setJsonParam(params, PARAMS.grouping, emptyArrayToUndefined(state.grouping));
+    setJsonParam(params, PARAMS.aggregation, state.aggregation);
+    setJsonParam(params, PARAMS.selection, emptyArrayToUndefined(state.selection));
+    return params.toString();
+}
+/** Decode URL query parameters produced by {@link serializeInteractionQueryState}. */
+export function parseInteractionQueryState(search) {
+    const params = typeof search === "string" ? new URLSearchParams(search.startsWith("?") ? search.slice(1) : search) : search;
+    return {
+        filters: parseRecordParam(params.get(PARAMS.filters)),
+        spatialFilter: parseRecordParam(params.get(PARAMS.spatialFilter)),
+        extent: parseRecordParam(params.get(PARAMS.extent)),
+        orderBy: parseArrayParam(params.get(PARAMS.orderBy)),
+        pagination: parseRecordParam(params.get(PARAMS.pagination)),
+        outFields: parseStringArrayParam(params.get(PARAMS.outFields)),
+        grouping: parseStringArrayParam(params.get(PARAMS.grouping)),
+        aggregation: parseRecordParam(params.get(PARAMS.aggregation)),
+        selection: parseSelection(params.get(PARAMS.selection)),
+    };
+}
+/** Return the query parameter names used by the shareable serializer. */
+export function interactionQueryParamNames() {
+    return { ...PARAMS };
+}
+function setJsonParam(params, name, value) {
+    if (value === undefined)
+        return;
+    params.set(name, stableStringify(value));
+}
+function stableStringify(value) {
+    return JSON.stringify(sortJsonValue(value));
+}
+function sortJsonValue(value) {
+    if (Array.isArray(value))
+        return value.map(sortJsonValue);
+    if (!value || typeof value !== "object")
+        return value;
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+        out[key] = sortJsonValue(value[key]);
+    }
+    return out;
+}
+function parseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseRecordParam(value) {
+    if (!value)
+        return undefined;
+    const parsed = parseJson(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
+}
+function parseArrayParam(value) {
+    if (!value)
+        return undefined;
+    const parsed = parseJson(value);
+    return Array.isArray(parsed) ? parsed : undefined;
+}
+function parseStringArrayParam(value) {
+    const parsed = parseArrayParam(value);
+    if (!parsed)
+        return undefined;
+    return parsed.filter((entry) => typeof entry === "string");
+}
+function emptyArrayToUndefined(value) {
+    return value && value.length > 0 ? value : undefined;
+}
+function emptyObjectToUndefined(value) {
+    return value && Object.keys(value).length > 0 ? value : undefined;
+}
+function isSelectionTarget(value) {
+    if (typeof value === "string" || typeof value === "number")
+        return true;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return typeof record.sourceId === "string" && (typeof record.id === "string" || typeof record.id === "number");
+}

package/map/feature-service-adapter.d.ts

@@ -0,0 +1,138 @@
+/**
+ * MapLibre runtime adapter for Honua feature-service sources.
+ *
+ * {@link createHonuaFeatureServiceLayer} (and the migration codemod) emit a
+ * custom `honua-feature-service` source type that MapLibre's renderer does not
+ * understand — adding it to a `maplibre-gl` `Map` directly is a silent no-op.
+ *
+ * This module bridges that gap. It fetches features through the SDK query path
+ * ({@link HonuaFeatureLayer}) and converts the Esri feature set into a standard
+ * GeoJSON `FeatureCollection`, then exposes it as a plain MapLibre `geojson`
+ * source spec that the renderer renders natively. Callers either:
+ *
+ *  - call {@link loadHonuaFeatureServiceGeoJson} to obtain a `geojson` source
+ *    spec they add to their style themselves, or
+ *  - call {@link registerHonuaFeatureServiceSources} to walk a {@link HonuaMap}
+ *    and live-patch every `honua-feature-service` source on a real MapLibre map
+ *    into a fetched `geojson` source.
+ *
+ * Raster Honua sources (`honua-map-service`, tile services) already project
+ * onto MapLibre-native sources and need no adapter; this fills in the feature
+ * (vector) asymmetry.
+ *
+ * @module
+ */
+import type { HonuaClient } from "../core/client.js";
+import type { EsriGeometryType } from "../core/types.js";
+import type { HonuaMap } from "./honua-map.js";
+/** A GeoJSON geometry produced by the adapter. */
+export interface AdapterGeoJsonGeometry {
+    type: string;
+    coordinates: unknown;
+}
+/** A GeoJSON feature produced by the adapter. */
+export interface AdapterGeoJsonFeature {
+    type: "Feature";
+    id?: string | number;
+    geometry: AdapterGeoJsonGeometry | null;
+    properties: Record<string, unknown>;
+}
+/** A GeoJSON feature collection produced by the adapter. */
+export interface AdapterGeoJsonFeatureCollection {
+    type: "FeatureCollection";
+    features: AdapterGeoJsonFeature[];
+}
+/** A standard MapLibre `geojson` source specification. */
+export interface MapLibreGeoJsonSourceSpecification {
+    type: "geojson";
+    data: AdapterGeoJsonFeatureCollection;
+    attribution?: string;
+}
+/** Options controlling how the adapter fetches feature-service data. */
+export interface LoadHonuaFeatureServiceGeoJsonOptions {
+    /** Server-side WHERE clause. Defaults to `"1=1"`. */
+    definitionExpression?: string;
+    /** Fields to request. Defaults to all (`["*"]`). */
+    outFields?: string[];
+    /** Output spatial reference WKID. GeoJSON requires `4326`; defaults to it. */
+    outSR?: number;
+    /** Page size for paginated fetching. */
+    pageSize?: number;
+    /** Maximum pages to fetch. */
+    maxPages?: number;
+    /** Attribution to attach to the produced source spec. */
+    attribution?: string;
+    /** Abort signal forwarded to the query. */
+    signal?: AbortSignal;
+}
+/**
+ * The minimal MapLibre `Map` surface the adapter mutates. Any object exposing
+ * these methods — including a real `maplibre-gl` `Map` — satisfies it.
+ */
+export interface FeatureServiceAdapterMap {
+    getSource(id: string): unknown;
+    addSource(id: string, source: unknown): void;
+    removeSource(id: string): void;
+}
+/**
+ * Convert a single Esri geometry into a GeoJSON geometry.
+ *
+ * Handles the geometry kinds a feature-service query returns (point,
+ * multipoint, polyline, polygon, envelope). Returns `null` when the geometry is
+ * absent or unrecognised so the feature still renders attribute-only.
+ */
+export declare function esriGeometryToGeoJson(geometry: Record<string, unknown> | null | undefined, geometryType: EsriGeometryType | undefined): AdapterGeoJsonGeometry | null;
+/**
+ * Convert an array of Esri features (attributes + geometry) into a GeoJSON
+ * `FeatureCollection`.
+ */
+export declare function esriFeaturesToGeoJson(features: ReadonlyArray<{
+    attributes?: Record<string, unknown>;
+    geometry?: Record<string, unknown> | null;
+}>, geometryType: EsriGeometryType | undefined): AdapterGeoJsonFeatureCollection;
+/**
+ * Fetch a Honua feature-service layer through the SDK and return a standard
+ * MapLibre `geojson` source specification that the renderer renders natively.
+ *
+ * @example
+ * ```ts
+ * const source = await loadHonuaFeatureServiceGeoJson(client, layer.source.url);
+ * map.addSource(layer.sourceId, source);
+ * map.addLayer(layer.layer);
+ * ```
+ */
+export declare function loadHonuaFeatureServiceGeoJson(client: HonuaClient, url: string, options?: LoadHonuaFeatureServiceGeoJsonOptions): Promise<MapLibreGeoJsonSourceSpecification>;
+/** Result of {@link registerHonuaFeatureServiceSources}. */
+export interface RegisterHonuaFeatureServiceSourcesResult {
+    /** Source ids that were fetched and wired as `geojson` sources. */
+    registered: string[];
+    /** Source ids that failed to load, with the error encountered. */
+    failed: Array<{
+        sourceId: string;
+        error: unknown;
+    }>;
+}
+/** Options for {@link registerHonuaFeatureServiceSources}. */
+export interface RegisterHonuaFeatureServiceSourcesOptions extends LoadHonuaFeatureServiceGeoJsonOptions {
+    /**
+     * Maximum number of feature-service sources to fetch concurrently. Defaults
+     * to {@link DEFAULT_REGISTER_CONCURRENCY}. Total load latency becomes the max
+     * of the per-source fetches rather than their sum.
+     */
+    concurrency?: number;
+}
+/**
+ * Walk a {@link HonuaMap} and replace every `honua-feature-service` source on a
+ * real MapLibre map with a fetched standard `geojson` source so feature layers
+ * actually render.
+ *
+ * Existing `geojson` sources are updated in place via `setData`; otherwise a new
+ * source is added. Layers should be added by the caller (or already present in
+ * the style) — this only manages the data sources.
+ *
+ * @param map - A `maplibre-gl` `Map` (or any {@link FeatureServiceAdapterMap}).
+ * @param honuaMap - The {@link HonuaMap} whose feature-service sources to wire.
+ * @param client - The Honua client used to fetch features.
+ */
+export declare function registerHonuaFeatureServiceSources(map: FeatureServiceAdapterMap, honuaMap: HonuaMap, client: HonuaClient, options?: RegisterHonuaFeatureServiceSourcesOptions): Promise<RegisterHonuaFeatureServiceSourcesResult>;
+//# sourceMappingURL=feature-service-adapter.d.ts.map

package/map/feature-service-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-service-adapter.d.ts","sourceRoot":"","sources":["../../../src/map/feature-service-adapter.ts"],"names":[],"mappings":"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"}

package/map/feature-service-adapter.js

@@ -0,0 +1,279 @@
+/**
+ * MapLibre runtime adapter for Honua feature-service sources.
+ *
+ * {@link createHonuaFeatureServiceLayer} (and the migration codemod) emit a
+ * custom `honua-feature-service` source type that MapLibre's renderer does not
+ * understand — adding it to a `maplibre-gl` `Map` directly is a silent no-op.
+ *
+ * This module bridges that gap. It fetches features through the SDK query path
+ * ({@link HonuaFeatureLayer}) and converts the Esri feature set into a standard
+ * GeoJSON `FeatureCollection`, then exposes it as a plain MapLibre `geojson`
+ * source spec that the renderer renders natively. Callers either:
+ *
+ *  - call {@link loadHonuaFeatureServiceGeoJson} to obtain a `geojson` source
+ *    spec they add to their style themselves, or
+ *  - call {@link registerHonuaFeatureServiceSources} to walk a {@link HonuaMap}
+ *    and live-patch every `honua-feature-service` source on a real MapLibre map
+ *    into a fetched `geojson` source.
+ *
+ * Raster Honua sources (`honua-map-service`, tile services) already project
+ * onto MapLibre-native sources and need no adapter; this fills in the feature
+ * (vector) asymmetry.
+ *
+ * @module
+ */
+import { HonuaFeatureLayer } from "../core/surfaces.js";
+import { parseFeatureLayerUrl } from "../esri-compat/url.js";
+/**
+ * Convert a single Esri geometry into a GeoJSON geometry.
+ *
+ * Handles the geometry kinds a feature-service query returns (point,
+ * multipoint, polyline, polygon, envelope). Returns `null` when the geometry is
+ * absent or unrecognised so the feature still renders attribute-only.
+ */
+export function esriGeometryToGeoJson(geometry, geometryType) {
+    if (!geometry) {
+        return null;
+    }
+    // Point geometries are recognisable structurally even without a declared
+    // type (queries that elide geometryType still return {x, y}).
+    if (geometryType === "esriGeometryPoint" || (geometry.x !== undefined && geometry.y !== undefined)) {
+        const x = asFiniteNumber(geometry.x);
+        const y = asFiniteNumber(geometry.y);
+        if (x === undefined || y === undefined)
+            return null;
+        return { type: "Point", coordinates: [x, y] };
+    }
+    if (geometryType === "esriGeometryMultipoint") {
+        const points = asArray(geometry.points)
+            .map(asCoordinatePair)
+            .filter((value) => value !== undefined);
+        return { type: "MultiPoint", coordinates: points };
+    }
+    if (geometryType === "esriGeometryPolyline") {
+        const paths = asArray(geometry.paths)
+            .map(asCoordinateArray)
+            .filter((path) => path.length > 0);
+        if (paths.length === 1) {
+            return { type: "LineString", coordinates: paths[0] };
+        }
+        return { type: "MultiLineString", coordinates: paths };
+    }
+    if (geometryType === "esriGeometryPolygon") {
+        const rings = asArray(geometry.rings)
+            .map(asCoordinateArray)
+            .filter((ring) => ring.length > 0);
+        // MapLibre does not enforce GeoJSON ring winding for rendering, so the
+        // adapter passes Esri rings through as a Polygon without re-nesting.
+        return { type: "Polygon", coordinates: rings };
+    }
+    if (geometryType === "esriGeometryEnvelope") {
+        const xmin = asFiniteNumber(geometry.xmin);
+        const ymin = asFiniteNumber(geometry.ymin);
+        const xmax = asFiniteNumber(geometry.xmax);
+        const ymax = asFiniteNumber(geometry.ymax);
+        if (xmin === undefined || ymin === undefined || xmax === undefined || ymax === undefined) {
+            return null;
+        }
+        return {
+            type: "Polygon",
+            coordinates: [
+                [
+                    [xmin, ymin],
+                    [xmax, ymin],
+                    [xmax, ymax],
+                    [xmin, ymax],
+                    [xmin, ymin],
+                ],
+            ],
+        };
+    }
+    return null;
+}
+/**
+ * Convert an array of Esri features (attributes + geometry) into a GeoJSON
+ * `FeatureCollection`.
+ */
+export function esriFeaturesToGeoJson(features, geometryType) {
+    return {
+        type: "FeatureCollection",
+        features: features.map((feature) => ({
+            type: "Feature",
+            geometry: esriGeometryToGeoJson(feature.geometry ?? null, geometryType),
+            properties: { ...(feature.attributes ?? {}) },
+        })),
+    };
+}
+/**
+ * Fetch a Honua feature-service layer through the SDK and return a standard
+ * MapLibre `geojson` source specification that the renderer renders natively.
+ *
+ * @example
+ * ```ts
+ * const source = await loadHonuaFeatureServiceGeoJson(client, layer.source.url);
+ * map.addSource(layer.sourceId, source);
+ * map.addLayer(layer.layer);
+ * ```
+ */
+export async function loadHonuaFeatureServiceGeoJson(client, url, options = {}) {
+    const parsed = parseFeatureLayerUrl(url);
+    const layer = new HonuaFeatureLayer({
+        client,
+        serviceId: parsed.serviceId,
+        layerId: parsed.layerId,
+    });
+    // GeoJSON is lon/lat (WGS84). Default outSR to 4326 so the rendered
+    // coordinates land where MapLibre expects them.
+    const outSR = options.outSR ?? 4326;
+    const request = {
+        where: options.definitionExpression ?? "1=1",
+        outFields: options.outFields ?? ["*"],
+        returnGeometry: true,
+        outSr: outSR,
+        ...(options.pageSize !== undefined ? { pageSize: options.pageSize } : {}),
+        ...(options.maxPages !== undefined ? { maxPages: options.maxPages } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+    };
+    const metadataPromise = layer.metadata(options.signal ? { signal: options.signal } : {}).catch(() => undefined);
+    const features = await layer.queryFeaturesAll(request);
+    const geometryType = (await metadataPromise)?.geometryType;
+    const data = esriFeaturesToGeoJson(features, geometryType);
+    return {
+        type: "geojson",
+        data,
+        ...(options.attribution ? { attribution: options.attribution } : {}),
+    };
+}
+/** Default fetch fan-out for {@link registerHonuaFeatureServiceSources}. */
+const DEFAULT_REGISTER_CONCURRENCY = 6;
+/**
+ * Walk a {@link HonuaMap} and replace every `honua-feature-service` source on a
+ * real MapLibre map with a fetched standard `geojson` source so feature layers
+ * actually render.
+ *
+ * Existing `geojson` sources are updated in place via `setData`; otherwise a new
+ * source is added. Layers should be added by the caller (or already present in
+ * the style) — this only manages the data sources.
+ *
+ * @param map - A `maplibre-gl` `Map` (or any {@link FeatureServiceAdapterMap}).
+ * @param honuaMap - The {@link HonuaMap} whose feature-service sources to wire.
+ * @param client - The Honua client used to fetch features.
+ */
+export async function registerHonuaFeatureServiceSources(map, honuaMap, client, options = {}) {
+    const registered = [];
+    const failed = [];
+    // Collect the feature-service sources to load, validating `url` up front so a
+    // missing url fails fast without consuming a fetch slot.
+    const pending = [];
+    for (const sourceId of honuaMap.sourceIds) {
+        const spec = honuaMap.getSourceSpec(sourceId);
+        if (!spec || spec.type !== "honua-feature-service") {
+            continue;
+        }
+        const url = spec.url;
+        if (typeof url !== "string" || url.length === 0) {
+            failed.push({ sourceId, error: new Error(`feature-service source "${sourceId}" is missing url`) });
+            continue;
+        }
+        pending.push({ sourceId, url, spec });
+    }
+    // Fetch sources with bounded concurrency: total latency becomes the max of the
+    // per-source fetches instead of their sum (a startup cliff for multi-layer maps).
+    const concurrency = typeof options.concurrency === "number" && Number.isFinite(options.concurrency)
+        ? Math.max(1, Math.trunc(options.concurrency))
+        : DEFAULT_REGISTER_CONCURRENCY;
+    const results = await allSettledLimited(pending, concurrency, (item) => loadHonuaFeatureServiceGeoJson(client, item.url, {
+        ...options,
+        ...featureServiceSpecOverrides(item.spec),
+    }));
+    // Apply the fetched sources to the map sequentially, preserving source order.
+    // Map mutations are synchronous and must stay single-threaded.
+    for (let index = 0; index < pending.length; index += 1) {
+        const { sourceId } = pending[index];
+        const result = results[index];
+        if (result.status === "rejected") {
+            failed.push({ sourceId, error: result.reason });
+            continue;
+        }
+        try {
+            const source = result.value;
+            const existing = map.getSource(sourceId);
+            if (existing && typeof existing.setData === "function") {
+                existing.setData(source.data);
+            }
+            else {
+                if (existing) {
+                    map.removeSource(sourceId);
+                }
+                map.addSource(sourceId, source);
+            }
+            registered.push(sourceId);
+        }
+        catch (error) {
+            failed.push({ sourceId, error });
+        }
+    }
+    return { registered, failed };
+}
+/** Derive per-source query overrides from a `honua-feature-service` source spec. */
+function featureServiceSpecOverrides(spec) {
+    return {
+        ...(typeof spec.definitionExpression === "string"
+            ? { definitionExpression: spec.definitionExpression }
+            : {}),
+        ...(Array.isArray(spec.outFields)
+            ? { outFields: spec.outFields }
+            : {}),
+        ...(typeof spec.outSR === "number" ? { outSR: spec.outSR } : {}),
+        ...(typeof spec.attribution === "string"
+            ? { attribution: spec.attribution }
+            : {}),
+    };
+}
+/**
+ * Run `worker` over `values` with at most `concurrency` in flight, collecting
+ * settled results in input order. Mirrors the limiter in `runtime/query-tiles`;
+ * kept local to avoid coupling the map layer to the runtime tile pipeline.
+ */
+async function allSettledLimited(values, concurrency, worker) {
+    const results = new Array(values.length);
+    let nextIndex = 0;
+    async function run() {
+        for (;;) {
+            const index = nextIndex;
+            nextIndex += 1;
+            if (index >= values.length)
+                return;
+            try {
+                results[index] = { status: "fulfilled", value: await worker(values[index]) };
+            }
+            catch (reason) {
+                results[index] = { status: "rejected", reason };
+            }
+        }
+    }
+    const workers = Array.from({ length: Math.min(concurrency, values.length) }, () => run());
+    await Promise.all(workers);
+    return results;
+}
+// ── Coercion helpers ─────────────────────────────────────────
+function asFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function asCoordinatePair(value) {
+    if (!Array.isArray(value) || value.length < 2)
+        return undefined;
+    const x = asFiniteNumber(value[0]);
+    const y = asFiniteNumber(value[1]);
+    if (x === undefined || y === undefined)
+        return undefined;
+    return [x, y];
+}
+function asCoordinateArray(value) {
+    return asArray(value)
+        .map(asCoordinatePair)
+        .filter((pair) => pair !== undefined);
+}