@honua/app-platform 0.0.20-alpha.0

package/interactions/hit-test.js

@@ -0,0 +1,291 @@
+/**
+ * Renderer-neutral hit-test and pointer primitives.
+ *
+ * The helpers in this module normalize MapLibre-shaped rendered features into
+ * Honua source-qualified identities without importing a renderer package.
+ *
+ * @module
+ */
+import { loadQueryTileFeatureDetail, mapQueryTileFeatureIdentity, } from "../contract/index.js";
+import { sourceFeatureSelectionTarget } from "../exploration/selection.js";
+export async function hitTestMap(map, input, options = {}) {
+    const pointer = normalizePointerEvent(input, map);
+    const degraded = pointer.lngLat
+        ? []
+        : [
+            {
+                reason: "lnglat-unavailable",
+                message: "The renderer did not provide lngLat and cannot unproject screen coordinates.",
+            },
+        ];
+    if (!map.queryRenderedFeatures) {
+        return {
+            point: pointer.point,
+            lngLat: pointer.lngLat,
+            features: [],
+            degraded: [
+                ...degraded,
+                { reason: "renderer-unsupported", message: "The renderer does not support queryRenderedFeatures." },
+            ],
+            rawFeatures: [],
+        };
+    }
+    const rawFeatures = map.queryRenderedFeatures(queryGeometry(pointer.point, options.tolerance), {
+        ...(options.layers ? { layers: options.layers } : {}),
+    });
+    const normalized = normalizeHitTestFeatures(rawFeatures, options);
+    const withDetails = options.loadDetails ? await loadHitDetails(normalized, options) : normalized;
+    return {
+        point: pointer.point,
+        lngLat: pointer.lngLat,
+        features: withDetails,
+        degraded,
+        rawFeatures,
+    };
+}
+export function normalizePointerEvent(input, map) {
+    const event = isRecord(input) ? input : {};
+    const point = normalizePoint(event.point) ?? normalizePoint(event) ?? clientPoint(event) ?? { x: 0, y: 0 };
+    const lngLat = normalizeLngLat(event.lngLat) ?? (map?.unproject ? normalizeLngLat(map.unproject(point)) : undefined);
+    return {
+        type: typeof event.type === "string" ? event.type : "pointer",
+        point,
+        ...(lngLat ? { lngLat } : {}),
+        originalEvent: input,
+    };
+}
+export function normalizeHitTestFeatures(features, options = {}) {
+    if (options.maxResults !== undefined && options.maxResults <= 0)
+        return [];
+    const out = [];
+    for (const feature of features) {
+        const context = featureContext(feature, options);
+        const hit = normalizeHitFeature(feature, context, options);
+        if (options.sourceIds && (!hit.sourceId || !options.sourceIds.includes(hit.sourceId)))
+            continue;
+        if (options.sourceLayers && (!hit.sourceLayer || !options.sourceLayers.includes(hit.sourceLayer)))
+            continue;
+        out.push(hit);
+        if (options.maxResults !== undefined && out.length >= options.maxResults)
+            break;
+    }
+    return out;
+}
+export function normalizeHitFeature(feature, context, options = {}) {
+    const properties = featureProperties(feature);
+    const queryTileDescriptor = context.queryTileDescriptor ?? queryTileDescriptorForContext(context, options);
+    const queryTileIdentity = queryTileDescriptor ? mapQueryTileFeatureIdentity(queryTileDescriptor, feature) : undefined;
+    const sourceId = queryTileIdentity?.sourceId ?? context.sourceId;
+    const sourceLayer = queryTileIdentity?.sourceLayer ?? context.sourceLayer;
+    const featureId = queryTileIdentity?.id ??
+        options.resolveFeatureId?.(feature, context) ??
+        featureIdFromFeature(feature, properties, options.featureIdProperty);
+    const geometry = featureGeometry(feature);
+    const raster = rasterSample(feature);
+    const degraded = [];
+    if (!sourceId) {
+        degraded.push({ reason: "source-binding-unavailable", message: "Rendered feature has no Honua source binding." });
+    }
+    if (featureId === undefined) {
+        degraded.push({
+            reason: "feature-id-unavailable",
+            message: "Rendered feature has no stable feature id.",
+            layerId: context.layerId,
+            sourceId,
+        });
+    }
+    if (geometry === undefined) {
+        degraded.push({
+            reason: "geometry-unavailable",
+            message: "Rendered feature did not include geometry.",
+            layerId: context.layerId,
+            sourceId,
+            featureId,
+        });
+    }
+    if (context.layerType === "raster" && raster?.value === undefined) {
+        degraded.push({
+            reason: "raster-value-unavailable",
+            message: "Rendered raster hit did not include a sample value.",
+            layerId: context.layerId,
+            sourceId,
+            featureId,
+        });
+    }
+    return {
+        layerId: context.layerId,
+        sourceId,
+        sourceLayer,
+        featureId,
+        ...(sourceId && featureId !== undefined
+            ? { selectionTarget: sourceFeatureSelectionTarget(sourceId, featureId, { sourceLayer }) }
+            : {}),
+        properties,
+        geometry,
+        raster,
+        rawFeature: feature,
+        degraded,
+    };
+}
+export function createQueryTileDetailLoader(sources, descriptors) {
+    return async (context, options) => {
+        const descriptor = descriptors[context.target.sourceId] ?? descriptors[context.sourceId ?? ""];
+        const source = sources[context.target.sourceId] ?? (context.sourceId ? sources[context.sourceId] : undefined);
+        if (!descriptor || !source)
+            return undefined;
+        return loadQueryTileFeatureDetail({
+            source,
+            descriptor,
+            target: context.target,
+            signal: options.signal,
+        });
+    };
+}
+async function loadHitDetails(features, options) {
+    if (!options.detailLoader) {
+        return features.map((hit) => ({
+            ...hit,
+            degraded: [
+                ...hit.degraded,
+                { reason: "detail-unavailable", message: "No hit-test detail loader was configured.", sourceId: hit.sourceId },
+            ],
+        }));
+    }
+    const out = [];
+    for (const hit of features) {
+        if (options.signal?.aborted) {
+            out.push(withDegraded(hit, "detail-aborted", "Hit-test detail loading was aborted."));
+            continue;
+        }
+        if (!hit.sourceId || hit.featureId === undefined) {
+            out.push(withDegraded(hit, "detail-unavailable", "Hit-test detail requires a source id and feature id."));
+            continue;
+        }
+        try {
+            const target = {
+                sourceId: hit.sourceId,
+                id: hit.featureId,
+                ...(hit.sourceLayer ? { sourceLayer: hit.sourceLayer } : {}),
+                properties: hit.properties,
+                feature: hit.rawFeature,
+            };
+            const detail = await options.detailLoader({ ...hit, target, hit }, { signal: options.signal });
+            out.push(detail === undefined ? withDegraded(hit, "detail-unavailable", "No detail was available.") : { ...hit, detail });
+        }
+        catch (cause) {
+            out.push(withDegraded(hit, options.signal?.aborted ? "detail-aborted" : "detail-failed", options.signal?.aborted ? "Hit-test detail loading was aborted." : "Hit-test detail loading failed.", cause));
+        }
+    }
+    return out;
+}
+function withDegraded(hit, reason, message, cause) {
+    return {
+        ...hit,
+        degraded: [
+            ...hit.degraded,
+            { reason, message, layerId: hit.layerId, sourceId: hit.sourceId, featureId: hit.featureId, cause },
+        ],
+    };
+}
+function queryGeometry(point, tolerance) {
+    const hitTolerance = tolerance ?? 0;
+    if (hitTolerance <= 0)
+        return point;
+    return [
+        { x: point.x - hitTolerance, y: point.y - hitTolerance },
+        { x: point.x + hitTolerance, y: point.y + hitTolerance },
+    ];
+}
+function featureContext(feature, options) {
+    const explicit = options.resolveFeatureContext?.(feature);
+    if (explicit)
+        return explicit;
+    const layerId = featureLayerId(feature);
+    return {
+        ...(layerId ? { layerId } : {}),
+        ...(layerId && options.featureContexts?.[layerId] ? options.featureContexts[layerId] : {}),
+        ...featureNativeSourceContext(feature),
+    };
+}
+function queryTileDescriptorForContext(context, options) {
+    if (!context.sourceId)
+        return undefined;
+    return options.queryTileSources?.[context.sourceId];
+}
+function normalizePoint(value) {
+    if (Array.isArray(value) && typeof value[0] === "number" && typeof value[1] === "number") {
+        return { x: value[0], y: value[1] };
+    }
+    if (isRecord(value) && typeof value.x === "number" && typeof value.y === "number") {
+        return { x: value.x, y: value.y };
+    }
+    return undefined;
+}
+function normalizeLngLat(value) {
+    if (Array.isArray(value) && typeof value[0] === "number" && typeof value[1] === "number")
+        return [value[0], value[1]];
+    if (isRecord(value) && typeof value.lng === "number" && typeof value.lat === "number")
+        return [value.lng, value.lat];
+    return undefined;
+}
+function clientPoint(value) {
+    return typeof value.clientX === "number" && typeof value.clientY === "number"
+        ? { x: value.clientX, y: value.clientY }
+        : undefined;
+}
+function featureIdFromFeature(feature, properties, featureIdProperty) {
+    if (isRecord(feature) && (typeof feature.id === "string" || typeof feature.id === "number"))
+        return feature.id;
+    const propertyId = (featureIdProperty ? properties[featureIdProperty] : undefined) ??
+        properties.OBJECTID ??
+        properties.objectid ??
+        properties.ObjectID ??
+        properties.id;
+    return typeof propertyId === "string" || typeof propertyId === "number" ? propertyId : undefined;
+}
+function featureProperties(feature) {
+    return isRecord(feature) && isRecord(feature.properties) ? feature.properties : {};
+}
+function featureGeometry(feature) {
+    return isRecord(feature) && "geometry" in feature ? feature.geometry : undefined;
+}
+function featureLayerId(feature) {
+    if (!isRecord(feature))
+        return undefined;
+    const layer = feature.layer;
+    return isRecord(layer) && typeof layer.id === "string" ? layer.id : undefined;
+}
+function featureNativeSourceContext(feature) {
+    if (!isRecord(feature))
+        return {};
+    const layer = isRecord(feature.layer) ? feature.layer : {};
+    const sourceId = typeof feature.source === "string" ? feature.source : typeof layer.source === "string" ? layer.source : undefined;
+    const sourceLayer = typeof feature.sourceLayer === "string"
+        ? feature.sourceLayer
+        : typeof feature.sourceLayer === "number"
+            ? String(feature.sourceLayer)
+            : typeof layer["source-layer"] === "string"
+                ? layer["source-layer"]
+                : undefined;
+    return {
+        ...(typeof layer.id === "string" ? { layerId: layer.id } : {}),
+        ...(typeof layer.type === "string" ? { layerType: layer.type } : {}),
+        ...(sourceId ? { sourceId } : {}),
+        ...(sourceLayer ? { sourceLayer } : {}),
+    };
+}
+function rasterSample(feature) {
+    if (!isRecord(feature))
+        return undefined;
+    const sample = feature.raster ?? feature.sample;
+    if (!isRecord(sample))
+        return undefined;
+    return {
+        value: sample.value,
+        band: typeof sample.band === "number" || typeof sample.band === "string" ? sample.band : undefined,
+        metadata: isRecord(sample.metadata) ? sample.metadata : undefined,
+    };
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/interactions/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `@honua/sdk-js/interactions` — hit-test, pointer normalization, and the
+ * binding primitives that wire chart / map / table widgets to an
+ * `ExplorationContext`.
+ *
+ * @example
+ * ```ts
+ * import { hitTestMap, bindMapSelectionToExploration } from "@honua/sdk-js/interactions";
+ *
+ * map.on("click", async (event) => {
+ *   const hit = await hitTestMap(map, event);
+ *   if (hit?.feature) ctx.dispatch({ type: "select", target: hit.feature });
+ * });
+ * bindMapSelectionToExploration({ map, context: ctx, sourceId: "parcels" });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { createQueryTileDetailLoader, hitTestMap, normalizeHitFeature, normalizeHitTestFeatures, normalizePointerEvent, } from "./hit-test.js";
+export { extentToSpatialFilter, selectLinkedViewQueryProjection, subscribeExplorationSelector, } from "../exploration/selectors.js";
+export { setFeatureState, getFeatureState, removeFeatureState, createHoverHandler, createSelectionHandler, } from "./feature-state.js";
+export { bindDetailToSelection, bindChartToExploration, bindFilterControlsToExploration, bindMapExtentToExploration, bindMapSelectionToExploration, bindQueryProjectionToExploration, bindTableSelectionToExploration, syncMapLayerFilterToExploration, syncFeatureStateSelection, } from "./exploration-bindings.js";
+export { preparePrimaryDetailModel, prepareSelectionDetailModels } from "./detail-model.js";
+export { interactionQueryParamNames, parseInteractionQueryState, parseSelection, serializeInteractionQueryState, serializeSelection, } from "./share-state.js";
+export type { HonuaHitFeature, HonuaHitTestDegradedReason, HonuaHitTestDegradedState, HonuaHitTestDetailContext, HonuaHitTestDetailLoader, HonuaHitTestFeatureOptions, HonuaHitTestMap, HonuaHitTestOptions, HonuaHitTestRasterSample, HonuaHitTestResult, HonuaLngLat, HonuaNormalizeHitTestOptions, HonuaPointerEvent, HonuaPointerEventType, HonuaPointerInput, HonuaRenderedFeatureContext, HonuaScreenPoint, } from "./hit-test.js";
+export type { FeatureStateMap, MapEventTarget, InteractiveMap, FeatureTarget, HoverHandlerOptions, HoverHandle, SelectionHandlerOptions, SelectionHandle, } from "./feature-state.js";
+export type { ExplorationSelector, ExplorationSelectorListener, ExplorationSelectorSubscribeOptions, LinkedViewQueryProjection, LinkedViewQueryProjectionOptions, LinkedViewSpatialMode, } from "../exploration/selectors.js";
+export type { FeatureStateSelectionSyncOptions, ChartBucketSelection, ChartBucketSelectionOptions, ChartExplorationBinding, FilterControlsExplorationBinding, InteractionBindingHandle, LinkedViewQueryBindingOptions, MapExtentExplorationBindingOptions, MapExtentExplorationSource, MapLayerFilterExplorationBindingOptions, MapLayerFilterTarget, MapSelectionExplorationBindingOptions, SelectionDetailListener, TableSelectionExplorationBinding, } from "./exploration-bindings.js";
+export type { DetailFeatureLike, DetailFieldDefinition, DetailFieldModel, DetailModel, DetailModelOptions, DetailSelectionStatus, } from "./detail-model.js";
+export type { ShareableInteractionQueryParams, ShareableInteractionQueryState } from "./share-state.js";
+//# sourceMappingURL=index.d.ts.map

package/interactions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/interactions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EACL,2BAA2B,EAC3B,UAAU,EACV,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,qBAAqB,EACrB,+BAA+B,EAC/B,4BAA4B,GAC7B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,+BAA+B,EAC/B,0BAA0B,EAC1B,6BAA6B,EAC7B,gCAAgC,EAChC,+BAA+B,EAC/B,+BAA+B,EAC/B,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,yBAAyB,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAC;AAC5F,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,EAC1B,cAAc,EACd,8BAA8B,EAC9B,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,eAAe,EACf,0BAA0B,EAC1B,yBAAyB,EACzB,yBAAyB,EACzB,wBAAwB,EACxB,0BAA0B,EAC1B,eAAe,EACf,mBAAmB,EACnB,wBAAwB,EACxB,kBAAkB,EAClB,WAAW,EACX,4BAA4B,EAC5B,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,2BAA2B,EAC3B,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,eAAe,EACf,cAAc,EACd,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,WAAW,EACX,uBAAuB,EACvB,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,mBAAmB,EACnB,2BAA2B,EAC3B,mCAAmC,EACnC,yBAAyB,EACzB,gCAAgC,EAChC,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EACV,gCAAgC,EAChC,oBAAoB,EACpB,2BAA2B,EAC3B,uBAAuB,EACvB,gCAAgC,EAChC,wBAAwB,EACxB,6BAA6B,EAC7B,kCAAkC,EAClC,0BAA0B,EAC1B,uCAAuC,EACvC,oBAAoB,EACpB,qCAAqC,EACrC,uBAAuB,EACvB,gCAAgC,GACjC,MAAM,2BAA2B,CAAC;AACnC,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,+BAA+B,EAAE,8BAA8B,EAAE,MAAM,kBAAkB,CAAC"}

package/interactions/index.js

@@ -0,0 +1,24 @@
+/**
+ * `@honua/sdk-js/interactions` — hit-test, pointer normalization, and the
+ * binding primitives that wire chart / map / table widgets to an
+ * `ExplorationContext`.
+ *
+ * @example
+ * ```ts
+ * import { hitTestMap, bindMapSelectionToExploration } from "@honua/sdk-js/interactions";
+ *
+ * map.on("click", async (event) => {
+ *   const hit = await hitTestMap(map, event);
+ *   if (hit?.feature) ctx.dispatch({ type: "select", target: hit.feature });
+ * });
+ * bindMapSelectionToExploration({ map, context: ctx, sourceId: "parcels" });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { createQueryTileDetailLoader, hitTestMap, normalizeHitFeature, normalizeHitTestFeatures, normalizePointerEvent, } from "./hit-test.js";
+export { extentToSpatialFilter, selectLinkedViewQueryProjection, subscribeExplorationSelector, } from "../exploration/selectors.js";
+export { setFeatureState, getFeatureState, removeFeatureState, createHoverHandler, createSelectionHandler, } from "./feature-state.js";
+export { bindDetailToSelection, bindChartToExploration, bindFilterControlsToExploration, bindMapExtentToExploration, bindMapSelectionToExploration, bindQueryProjectionToExploration, bindTableSelectionToExploration, syncMapLayerFilterToExploration, syncFeatureStateSelection, } from "./exploration-bindings.js";
+export { preparePrimaryDetailModel, prepareSelectionDetailModels } from "./detail-model.js";
+export { interactionQueryParamNames, parseInteractionQueryState, parseSelection, serializeInteractionQueryState, serializeSelection, } from "./share-state.js";

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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"}