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

package/query-planner/wfs.js

@@ -0,0 +1,71 @@
+import { UNSUPPORTED_FES, compileSpatialFilter, compileWhere, serializeFes } from "../core/wfs-filter.js";
+import { HonuaQueryPlanningError } from "./types.js";
+export { compileSemanticWfsQuery } from "./wfs-semantic.js";
+/** Compile canonical query IR to a deterministic WFS 2.0 GetFeature request. */
+export function compileWfsQuery(source, query) {
+    if (source.protocol !== "wfs") {
+        throw new HonuaQueryPlanningError("unsupported-compiler", `wfs-2.0-get-feature-v1 does not compile protocol "${source.protocol}"`);
+    }
+    if (!source.typeName) {
+        throw new HonuaQueryPlanningError("invalid-query", `Source "${source.id}" requires locator.typeName for WFS planning`);
+    }
+    if (query.aggregation) {
+        throw new HonuaQueryPlanningError("unsupported-query", "WFS 2.0 has no portable remote aggregation; use degraded policy with an explicit bounded-local fallback");
+    }
+    if (query.spatialFilter && query.outSr !== undefined) {
+        throw new HonuaQueryPlanningError("unsupported-query", "WFS planning cannot use outSr to label input filter coordinates; stamp the input geometry through the typed WFS escape hatch");
+    }
+    // Keep this aligned with the current WFS adapter's reviewed default. A
+    // vendor-specific geometry property requires the typed WFS escape hatch
+    // until discovery carries that binding into both planner and executor.
+    const geometryProperty = "the_geom";
+    const filters = [];
+    if (query.where) {
+        const where = compileWhere(query.where.expression);
+        if (where === UNSUPPORTED_FES) {
+            throw new HonuaQueryPlanningError("unsupported-query", "The where clause is not expressible as FES 2.0");
+        }
+        if (where.kind !== "and" || where.operands.length > 0)
+            filters.push(where);
+    }
+    if (query.spatialFilter) {
+        const spatial = compileSpatialFilter({
+            geometry: query.spatialFilter.geometry,
+            geometryType: query.spatialFilter.geometryType,
+            ...(query.spatialFilter.spatialRel ? { spatialRel: query.spatialFilter.spatialRel } : {}),
+        }, {
+            geometryProperty,
+        });
+        if (spatial === UNSUPPORTED_FES) {
+            throw new HonuaQueryPlanningError("unsupported-query", "The spatial predicate is not expressible as FES 2.0");
+        }
+        filters.push(spatial);
+    }
+    let propertyName;
+    if (query.outFields && query.outFields.length > 0) {
+        const fields = [...query.outFields];
+        if (query.returnGeometry === false && fields.includes(geometryProperty)) {
+            throw new HonuaQueryPlanningError("unsupported-query", `WFS returnGeometry=false conflicts with outFields containing the geometry property "${geometryProperty}"`);
+        }
+        if (query.returnGeometry !== false && !fields.includes(geometryProperty))
+            fields.push(geometryProperty);
+        propertyName = fields;
+    }
+    else if (query.returnGeometry === false) {
+        throw new HonuaQueryPlanningError("unsupported-query", "WFS returnGeometry=false requires explicit outFields because propertyName cannot otherwise suppress geometry exactly");
+    }
+    return {
+        compiler: "wfs-2.0-get-feature-v1",
+        typeName: source.typeName,
+        ...(filters.length > 0 ? { filter: serializeFes(filters, { typeName: source.typeName }) } : {}),
+        ...(propertyName ? { propertyName } : {}),
+        ...(query.orderBy && query.orderBy.length > 0
+            ? {
+                sortBy: query.orderBy.map((sort) => `${sort.field} ${sort.direction === "desc" ? "DESC" : "ASC"}`).join(","),
+            }
+            : {}),
+        ...(query.pagination?.offset !== undefined ? { startIndex: query.pagination.offset } : {}),
+        ...(query.pagination?.limit !== undefined ? { count: query.pagination.limit } : {}),
+        ...(query.outSr !== undefined ? { srsName: String(query.outSr) } : {}),
+    };
+}

package/react/external-map.d.ts

@@ -0,0 +1,67 @@
+/**
+ * External-map interop for `@honua/react` (REQ-001 of the react depth pass).
+ *
+ * Every map-attached hook/component in this package resolves its MapLibre map
+ * through {@link useHonuaMap}: an explicit prop/argument wins, then the nearest
+ * {@link HonuaMapProvider} (or enclosing `HonuaMap`, which publishes the same
+ * context). The map is duck-typed as the data-to-map bridge's
+ * {@link DataToMapLibreMap} — any real `maplibre-gl` `Map` instance satisfies
+ * it, including the instance exposed by `@vis.gl/react-maplibre`'s `useMap()`
+ * (`mapRef.getMap()`). `@vis.gl/react-maplibre` is **not** a dependency; the
+ * interop is purely structural.
+ *
+ * SSR-safe: no `window` / `document` access at module scope.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { DataToMapLibreMap } from "../map/data-to-map-bridge.js";
+/**
+ * Context carrying the active, externally-visible MapLibre map instance.
+ * Populated by {@link HonuaMapProvider} and by `HonuaMap` (for its own map),
+ * so `useHonuaMap` always resolves the nearest enclosing map.
+ *
+ * @experimental
+ */
+export declare const HonuaExternalMapContext: import("react").Context<DataToMapLibreMap | null>;
+/** Props for {@link HonuaMapProvider}. @experimental */
+export interface HonuaMapProviderProps {
+    /**
+     * The externally-owned MapLibre map (duck-typed). Pass `null`/`undefined`
+     * while the map is still being created — descendants simply wait.
+     */
+    map: DataToMapLibreMap | null | undefined;
+    children?: ReactNode;
+}
+/**
+ * Publish an externally-owned MapLibre map to the Honua map-attached hooks and
+ * components below it ({@link HonuaSourceLayer}, {@link useMountedSource},
+ * selection bindings). Use this when another library owns the map — e.g.
+ * `@vis.gl/react-maplibre`'s `<Map>` — and Honua should only mount data onto
+ * it. The provider never mutates or removes the map.
+ *
+ * @example
+ * ```tsx
+ * function Overlay() {
+ *   const { current } = useMap(); // @vis.gl/react-maplibre
+ *   return (
+ *     <HonuaMapProvider map={current?.getMap() ?? null}>
+ *       <HonuaSourceLayer source={source} hover />
+ *     </HonuaMapProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @experimental
+ */
+export declare function HonuaMapProvider({ map, children }: HonuaMapProviderProps): ReactNode;
+/**
+ * Resolve the MapLibre map a map-attached hook/component should target: the
+ * explicit `map` argument when given, otherwise the nearest enclosing
+ * {@link HonuaMapProvider} or `HonuaMap`. Returns `null` while no map is
+ * available (SSR, or before the map finished creating).
+ *
+ * @experimental
+ */
+export declare function useHonuaMap(map?: DataToMapLibreMap | null): DataToMapLibreMap | null;
+//# sourceMappingURL=external-map.d.ts.map

package/react/external-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-map.d.ts","sourceRoot":"","sources":["../../../src/react/external-map.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,KAAK,SAAS,EAA6B,MAAM,OAAO,CAAC;AAElE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAEtE;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,mDAAgD,CAAC;AAGrF,wDAAwD;AACxD,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,GAAG,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,qBAAqB,GAAG,SAAS,CAEpF;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,CAAC,EAAE,iBAAiB,GAAG,IAAI,GAAG,iBAAiB,GAAG,IAAI,CAGpF"}

package/react/external-map.js

@@ -0,0 +1,63 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * External-map interop for `@honua/react` (REQ-001 of the react depth pass).
+ *
+ * Every map-attached hook/component in this package resolves its MapLibre map
+ * through {@link useHonuaMap}: an explicit prop/argument wins, then the nearest
+ * {@link HonuaMapProvider} (or enclosing `HonuaMap`, which publishes the same
+ * context). The map is duck-typed as the data-to-map bridge's
+ * {@link DataToMapLibreMap} — any real `maplibre-gl` `Map` instance satisfies
+ * it, including the instance exposed by `@vis.gl/react-maplibre`'s `useMap()`
+ * (`mapRef.getMap()`). `@vis.gl/react-maplibre` is **not** a dependency; the
+ * interop is purely structural.
+ *
+ * SSR-safe: no `window` / `document` access at module scope.
+ *
+ * @module
+ */
+import { createContext, useContext } from "react";
+/**
+ * Context carrying the active, externally-visible MapLibre map instance.
+ * Populated by {@link HonuaMapProvider} and by `HonuaMap` (for its own map),
+ * so `useHonuaMap` always resolves the nearest enclosing map.
+ *
+ * @experimental
+ */
+export const HonuaExternalMapContext = createContext(null);
+HonuaExternalMapContext.displayName = "HonuaExternalMapContext";
+/**
+ * Publish an externally-owned MapLibre map to the Honua map-attached hooks and
+ * components below it ({@link HonuaSourceLayer}, {@link useMountedSource},
+ * selection bindings). Use this when another library owns the map — e.g.
+ * `@vis.gl/react-maplibre`'s `<Map>` — and Honua should only mount data onto
+ * it. The provider never mutates or removes the map.
+ *
+ * @example
+ * ```tsx
+ * function Overlay() {
+ *   const { current } = useMap(); // @vis.gl/react-maplibre
+ *   return (
+ *     <HonuaMapProvider map={current?.getMap() ?? null}>
+ *       <HonuaSourceLayer source={source} hover />
+ *     </HonuaMapProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @experimental
+ */
+export function HonuaMapProvider({ map, children }) {
+    return _jsx(HonuaExternalMapContext.Provider, { value: map ?? null, children: children });
+}
+/**
+ * Resolve the MapLibre map a map-attached hook/component should target: the
+ * explicit `map` argument when given, otherwise the nearest enclosing
+ * {@link HonuaMapProvider} or `HonuaMap`. Returns `null` while no map is
+ * available (SSR, or before the map finished creating).
+ *
+ * @experimental
+ */
+export function useHonuaMap(map) {
+    const contextMap = useContext(HonuaExternalMapContext);
+    return map ?? contextMap;
+}

package/react/honua-map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"honua-map.d.ts","sourceRoot":"","sources":["../../../src/react/honua-map.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,SAAS,EAA+B,MAAM,OAAO,CAAC;AAExF,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAMhH,oFAAoF;AACpF,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,GAAG,WAAW,CAAC;IAChC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,KAAK,OAAO,EAAE,kBAAkB,KAAK,WAAW,GAAG;QAAE,MAAM,IAAI,IAAI,CAAA;KAAE,CAAC;IAC3E,KAAK,EAAE,KAAK,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;CAC3D;AAID,kCAAkC;AAClC,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,OAAO,EAAE,eAAe,CAAC;IACzB;;;;OAIG;IACH,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,WAAW,CAAC,CAAC,CAAC;IAC5D;;;;OAIG;IACH,WAAW,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,CAAC,CAAC;IACpD,wCAAwC;IACxC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAC;IAC/C,uDAAuD;IACvD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,CAiGxD"}
+{"version":3,"file":"honua-map.d.ts","sourceRoot":"","sources":["../../../src/react/honua-map.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,SAAS,EAA+B,MAAM,OAAO,CAAC;AAGxF,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAOhH,oFAAoF;AACpF,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,GAAG,WAAW,CAAC;IAChC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,KAAK,OAAO,EAAE,kBAAkB,KAAK,WAAW,GAAG;QAAE,MAAM,IAAI,IAAI,CAAA;KAAE,CAAC;IAC3E,KAAK,EAAE,KAAK,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;CAC3D;AAID,kCAAkC;AAClC,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,OAAO,EAAE,eAAe,CAAC;IACzB;;;;OAIG;IACH,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,WAAW,CAAC,CAAC,CAAC;IAC5D;;;;OAIG;IACH,WAAW,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,CAAC,CAAC;IACpD,wCAAwC;IACxC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAC;IAC/C,uDAAuD;IACvD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,CAwGxD"}

package/react/honua-map.js

@@ -15,8 +15,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 import { useEffect, useRef, useState } from "react";
 import { loadMapPackage } from "../runtime/index.js";
-import { useHonuaClient } from "./hooks.js";
 import { HonuaMapContext } from "./context.js";
+import { HonuaExternalMapContext } from "./external-map.js";
+import { useHonuaClient } from "./hooks.js";
 const EMPTY_STYLE = { version: 8, sources: {}, layers: [] };
 /**
  * Render a Honua-composed MapLibre map.
@@ -105,5 +106,5 @@ export function HonuaMap(props) {
         runtime.updatePackage(mapPackage).catch((error) => onError?.(error));
         // biome-ignore lint/correctness/useExhaustiveDependencies: onError is a callback prop; re-running on its identity is undesirable.
     }, [contextValue.runtime, mapPackage]);
-    return (_jsxs(HonuaMapContext.Provider, { value: contextValue, children: [externalMap ? null : _jsx("div", { ref: containerRef, className: className, style: style, "data-honua-map": "" }), children] }));
+    return (_jsx(HonuaMapContext.Provider, { value: contextValue, children: _jsxs(HonuaExternalMapContext.Provider, { value: contextValue.map ?? null, children: [externalMap ? null : _jsx("div", { ref: containerRef, className: className, style: style, "data-honua-map": "" }), children] }) }));
 }

package/react/honua-source-layer.d.ts

@@ -0,0 +1,110 @@
+/**
+ * {@link HonuaSourceLayer} — the declarative face of the data-to-map bridge
+ * (REQ-002 of the react depth pass): mount a contract `Source` as a styled,
+ * interactive MapLibre layer set inside any enclosing map (`HonuaMap`, a
+ * {@link HonuaMapProvider}-published external map, or an explicit `map` prop).
+ *
+ * Prop changes diff in place (`query` → `setFilter`, `renderer.paint/layout` →
+ * property setters); unmounting disposes every bridge-owned MapLibre resource;
+ * React 18/19 StrictMode double-mounts neither leak nor double-add (see
+ * {@link useMountedSource}).
+ *
+ * SSR-safe: no `window` / `document` access at module scope.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import type { Query, Source } from "../contract/types.js";
+import type { DataToMapLibreMap, MountSourceOptions, MountedSourceDiagnostics, MountSourcePopupOptions } from "../map/data-to-map-bridge.js";
+import type { Renderer } from "../style/renderers.js";
+/**
+ * Declarative styling for a {@link HonuaSourceLayer}: the bridge's styling
+ * surface (geometry restriction, per-geometry paint/layout overrides, or a
+ * verbatim custom layer set). `paint` / `layout` changes are applied in place;
+ * `geometry` / `layers` changes remount the layer set.
+ *
+ * The `renderer` prop also accepts a first-class renderer object from
+ * `@honua/sdk-js/style` (`classBreaksRenderer`, `uniqueValueRenderer`,
+ * `heatmapRenderer`, `clusterRenderer`); changes diff through the handle's
+ * `setRenderer` without teardown.
+ *
+ * @experimental
+ */
+export type HonuaSourceRenderer<T = Record<string, unknown>> = Pick<MountSourceOptions<T>, "geometry" | "layers" | "paint" | "layout">;
+/** Props for {@link HonuaSourceLayer}. @experimental */
+export interface HonuaSourceLayerProps<T = Record<string, unknown>> {
+    /** The contract `Source` to mount. `null` while it is still resolving. */
+    source: Source<T> | null | undefined;
+    /**
+     * Target map. Omit to resolve the nearest enclosing `HonuaMap` /
+     * {@link HonuaMapProvider} (external-map interop).
+     */
+    map?: DataToMapLibreMap | null;
+    /** Filter applied to the mounted data; changes diff via `setFilter`. */
+    query?: Readonly<Omit<Query<T>, "signal">>;
+    /**
+     * Styling: either a first-class renderer object from `@honua/sdk-js/style`
+     * (diffed via `setRenderer`) or a {@link HonuaSourceRenderer} bag of
+     * geometry restriction + paint/layout overrides or custom layers.
+     */
+    renderer?: HonuaSourceRenderer<T> | Renderer;
+    /** Open a popup on feature click (`factory` usually `() => new maplibregl.Popup()`). */
+    popup?: MountSourcePopupOptions;
+    /** Toggle hover feature-state on the mounted layers (bridge `hover` option). */
+    hover?: boolean | {
+        readonly stateKey?: string;
+    };
+    /**
+     * Share feature selection with the enclosing `HonuaSelectionProvider`:
+     * clicks toggle the shared selection and the shared selection is mirrored
+     * onto feature-state (default key `"selected"`). Also publishes hover to the
+     * provider when {@link hover} is enabled. No-op without a provider.
+     */
+    selection?: boolean | {
+        readonly stateKey?: string;
+        readonly multiSelect?: boolean;
+    };
+    /** When `false`, nothing is mounted. @default true */
+    enabled?: boolean;
+    /** Called with fresh diagnostics after the mount and each applied update. */
+    onDiagnostics?: (diagnostics: MountedSourceDiagnostics) => void;
+    /** Called when mounting or an update fails. */
+    onError?: (error: unknown) => void;
+    /** Force a bridge strategy (`"geojson"` / `"query-tiles"`). */
+    strategy?: MountSourceOptions<T>["strategy"];
+    /** MapLibre source id override. @default `honua-<descriptor id>` */
+    sourceId?: string;
+    /** Base layer id override; geometry suffixes are appended. */
+    layerId?: string;
+    /** Existing layer id to insert the bridge layers before. */
+    beforeId?: string;
+    /** GeoJSON materialization bound. @default 10000 */
+    maxGeoJsonFeatures?: number;
+    /** Dynamic query-tile descriptor enabling the tile strategy. */
+    queryTiles?: MountSourceOptions<T>["queryTiles"];
+    /** Vector `source-layer` for the tile strategy. */
+    sourceLayer?: string;
+    /** Attribution override. */
+    attribution?: string;
+    /** Fit the map to the mounted data. */
+    fitBounds?: MountSourceOptions<T>["fitBounds"];
+}
+/**
+ * Mount a contract `Source` through the data-to-map bridge, declaratively.
+ * Renders nothing itself.
+ *
+ * @example
+ * ```tsx
+ * <HonuaSourceLayer
+ *   source={source}
+ *   query={{ where: "STATUS = 'OPEN'" }}
+ *   renderer={{ paint: { point: { "circle-color": "#38bdf8" } } }}
+ *   hover
+ *   selection
+ * />
+ * ```
+ *
+ * @experimental
+ */
+export declare function HonuaSourceLayer<T = Record<string, unknown>>(props: HonuaSourceLayerProps<T>): ReactNode;
+//# sourceMappingURL=honua-source-layer.d.ts.map

package/react/honua-source-layer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"honua-source-layer.d.ts","sourceRoot":"","sources":["../../../src/react/honua-source-layer.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAKtD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,IAAI,CACjE,kBAAkB,CAAC,CAAC,CAAC,EACrB,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAC3C,CAAC;AAYF,wDAAwD;AACxD,MAAM,WAAW,qBAAqB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAChE,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;IACrC;;;OAGG;IACH,GAAG,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC/B,wEAAwE;IACxE,KAAK,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC;IAC7C,wFAAwF;IACxF,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,gFAAgF;IAChF,KAAK,CAAC,EAAE,OAAO,GAAG;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACrF,sDAAsD;IACtD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6EAA6E;IAC7E,aAAa,CAAC,EAAE,CAAC,WAAW,EAAE,wBAAwB,KAAK,IAAI,CAAC;IAChE,+CAA+C;IAC/C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IAC7C,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,gEAAgE;IAChE,UAAU,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;IACjD,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4BAA4B;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,SAAS,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,SAAS,CA+DxG"}

package/react/honua-source-layer.js

@@ -0,0 +1,101 @@
+/**
+ * {@link HonuaSourceLayer} — the declarative face of the data-to-map bridge
+ * (REQ-002 of the react depth pass): mount a contract `Source` as a styled,
+ * interactive MapLibre layer set inside any enclosing map (`HonuaMap`, a
+ * {@link HonuaMapProvider}-published external map, or an explicit `map` prop).
+ *
+ * Prop changes diff in place (`query` → `setFilter`, `renderer.paint/layout` →
+ * property setters); unmounting disposes every bridge-owned MapLibre resource;
+ * React 18/19 StrictMode double-mounts neither leak nor double-add (see
+ * {@link useMountedSource}).
+ *
+ * SSR-safe: no `window` / `document` access at module scope.
+ *
+ * @module
+ */
+import { useMemo } from "react";
+import { useHonuaMap } from "./external-map.js";
+import { useMapHoverBinding, useMapSelectionBinding } from "./selection.js";
+import { useMountedSource } from "./use-mounted-source.js";
+/** Recognize a first-class renderer object from `@honua/sdk-js/style`. */
+function isRendererObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.kind === "string" &&
+        typeof value.toMapLibre === "function");
+}
+/**
+ * Mount a contract `Source` through the data-to-map bridge, declaratively.
+ * Renders nothing itself.
+ *
+ * @example
+ * ```tsx
+ * <HonuaSourceLayer
+ *   source={source}
+ *   query={{ where: "STATUS = 'OPEN'" }}
+ *   renderer={{ paint: { point: { "circle-color": "#38bdf8" } } }}
+ *   hover
+ *   selection
+ * />
+ * ```
+ *
+ * @experimental
+ */
+export function HonuaSourceLayer(props) {
+    const map = useHonuaMap(props.map);
+    // The renderer prop carries either a first-class renderer object (routed to
+    // the bridge's `renderer` option, diffed via setRenderer) or the
+    // geometry-default styling bag (diffed via property setters).
+    const rendererObject = isRendererObject(props.renderer) ? props.renderer : undefined;
+    const styleRenderer = rendererObject === undefined ? props.renderer : undefined;
+    const { handle, diagnostics } = useMountedSource(map, props.source, {
+        enabled: props.enabled,
+        query: props.query,
+        renderer: rendererObject,
+        geometry: styleRenderer?.geometry,
+        layers: styleRenderer?.layers,
+        paint: styleRenderer?.paint,
+        layout: styleRenderer?.layout,
+        popup: props.popup,
+        hover: props.hover,
+        onDiagnostics: props.onDiagnostics,
+        onError: props.onError,
+        strategy: props.strategy,
+        sourceId: props.sourceId,
+        layerId: props.layerId,
+        beforeId: props.beforeId,
+        maxGeoJsonFeatures: props.maxGeoJsonFeatures,
+        queryTiles: props.queryTiles,
+        sourceLayer: props.sourceLayer,
+        attribution: props.attribution,
+        fitBounds: props.fitBounds,
+    });
+    // Interactive layers exclude the polygon outline companion, mirroring the
+    // bridge's own popup/hover wiring. Re-read after every applied update
+    // (`diagnostics` changes) — a structural setRenderer swap replaces the
+    // owned layer ids on the same handle.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: `diagnostics` signals layer-set changes; ids are read from the handle getter.
+    const interactiveLayerIds = useMemo(() => (handle ? handle.layerIds.filter((id) => !id.endsWith("-polygon-outline")) : []), [handle, diagnostics]);
+    const selection = props.selection;
+    const selectionEnabled = Boolean(selection) && handle !== null;
+    // Bind against the handle's *resolved* source-layer — the explicit prop or
+    // the default the bridge derived from the query-tile descriptor. MapLibre
+    // scopes vector-tile feature-state by source-layer, so the binding must
+    // target the exact value the mounted layers render with.
+    const resolvedSourceLayer = handle?.sourceLayer ?? props.sourceLayer;
+    useMapSelectionBinding(map, {
+        sourceId: handle?.sourceId ?? "",
+        layerIds: interactiveLayerIds,
+        sourceLayer: resolvedSourceLayer,
+        stateKey: typeof selection === "object" ? selection.stateKey : undefined,
+        multiSelect: typeof selection === "object" ? selection.multiSelect : undefined,
+        enabled: selectionEnabled,
+    });
+    useMapHoverBinding(map, {
+        sourceId: handle?.sourceId ?? "",
+        layerIds: interactiveLayerIds,
+        sourceLayer: resolvedSourceLayer,
+        enabled: selectionEnabled && Boolean(props.hover),
+    });
+    return null;
+}

package/react/hooks.d.ts

@@ -56,6 +56,34 @@ export interface UseQueryOptions {
     enabled?: boolean;
     /** Use `source.queryAll()` (drain every page) instead of a single page. */
     drainAllPages?: boolean;
+    /**
+     * Stale-while-revalidate window in milliseconds. When a consumer (re)mounts
+     * or the query key changes and the cached result is at least this old, the
+     * cached data keeps rendering while a background refetch runs
+     * (`isFetching: true`, `data` preserved). `0` revalidates on every mount.
+     * Omitted keeps the historical behavior: cached results are served without
+     * revalidation until `refetch()` or an explicit invalidation.
+     *
+     * @experimental
+     */
+    staleTimeMs?: number;
+    /**
+     * Throw query errors during render so the nearest React error boundary
+     * receives them (typed errors such as `HonuaCapabilityNotSupportedError`
+     * arrive intact). Default `false`: errors are returned on the snapshot.
+     *
+     * @experimental
+     */
+    throwOnError?: boolean;
+    /**
+     * Suspense mode: while the first fetch (no cached data yet) is in flight the
+     * hook suspends, and errors are thrown to the nearest error boundary. Wrap
+     * consumers in `<Suspense fallback={…}>`. Background refetches do not
+     * suspend — cached data keeps rendering stale-while-revalidate style.
+     *
+     * @experimental
+     */
+    suspense?: boolean;
 }
 /** Result of {@link useQuery}: a stable snapshot plus a `refetch` trigger. */
 export interface UseQueryResult<T> extends QuerySnapshot<Result<T>> {

package/react/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../src/react/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EACV,gBAAgB,EAChB,OAAO,EACP,SAAS,EACT,KAAK,EACL,MAAM,EACN,MAAM,EACN,gBAAgB,EAChB,cAAc,EACf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAC5F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,aAAa,EAAiC,MAAM,kBAAkB,CAAC;AAU3G;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,WAAW,CAE5C;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAEpD;AAED,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,SAAS,CAAC;IACd,OAAO,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,aAAa,CAAC,EAAE,cAAc,CAAC;CAChC;AAcD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAqB9D;AAED,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,8EAA8E;AAC9E,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACjE,8DAA8D;IAC9D,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClD,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,IAAI,EACpC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,EAChB,OAAO,GAAE,eAAoB,GAC5B,cAAc,CAAC,CAAC,CAAC,CA2CnB;AAED,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yEAAyE;IACzE,OAAO,CAAC,EAAE,IAAI,CAAC,yBAAyB,EAAE,QAAQ,CAAC,CAAC;CACrD;AAED,yCAAyC;AACzC,MAAM,WAAW,qBAAsB,SAAQ,aAAa,CAAC,wBAAwB,CAAC;IACpF,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,qBAAqB,CAmC3F;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,eAAe,GAAG,IAAI,CAEtD;AAED,0EAA0E;AAC1E,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG;IAAE,KAAK,IAAI,IAAI,CAAA;CAAE,GAAG;IAAE,MAAM,IAAI,IAAI,CAAA;CAAE,GAAG;IAAE,WAAW,IAAI,IAAI,CAAA;CAAE,CAAC;AAE9G;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,CAAC,MAAM,eAAe,GAAG,SAAS,CAAC,GAAG,IAAI,GAAG,SAAS,EAC/D,IAAI,GAAE,SAAS,OAAO,EAAO,GAC5B,IAAI,CASN"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../src/react/hooks.ts"],"names":[],"mappings":"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"}

package/react/hooks.js

@@ -112,19 +112,41 @@ export function useQuery(source, query, options = {}) {
     const subscribe = useCallback((onStoreChange) => (key ? cache.subscribe(key, onStoreChange) : () => { }), [cache, key]);
     const getSnapshot = useCallback(() => (key ? cache.getSnapshot(key) : idleSnapshot()), [cache, key]);
     const snapshot = useSyncExternalStore(subscribe, getSnapshot, () => idleSnapshot());
+    const staleTimeMs = options.staleTimeMs;
+    // `key` already encodes source id + query + mode, so the fetcher (like the
+    // effects below) is intentionally keyed on it rather than on the identity of
+    // the `source` / `query` objects — an inline literal cannot thrash the cache.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: `key` already encodes source id + query + mode.
+    const fetcher = useCallback((signal) => drainAllPages
+        ? source.queryAll({ ...query, signal })
+        : source.query({ ...query, signal }), [key]);
     // biome-ignore lint/correctness/useExhaustiveDependencies: `key` already encodes source id + query + mode.
     useEffect(() => {
         if (!key || !source)
             return;
-        cache.ensure(key, (signal) => drainAllPages ? source.queryAll({ ...query, signal }) : source.query({ ...query, signal }));
-    }, [cache, key]);
+        cache.ensure(key, fetcher, staleTimeMs !== undefined ? { staleTimeMs } : {});
+    }, [cache, key, fetcher, staleTimeMs]);
     // biome-ignore lint/correctness/useExhaustiveDependencies: `key` already encodes source id + query + mode.
     const refetch = useCallback(() => {
         if (!key || !source)
             return;
-        cache.run(key, (signal) => drainAllPages ? source.queryAll({ ...query, signal }) : source.query({ ...query, signal }));
-    }, [cache, key]);
+        cache.run(key, fetcher);
+    }, [cache, key, fetcher]);
     useDebugValue(snapshot.status);
+    if (key && source && (options.suspense || options.throwOnError) && snapshot.status === "error") {
+        // Surface the typed error (e.g. HonuaCapabilityNotSupportedError) to the
+        // nearest error boundary. `refetch()` from the boundary retries.
+        throw snapshot.error;
+    }
+    if (options.suspense && key && source && snapshot.data === undefined) {
+        // First load with no cached data: kick the fetch during render (idempotent
+        // — `ensure` is a no-op once the entry left `idle`, so StrictMode's double
+        // render cannot double-fetch) and suspend on its promise.
+        cache.ensure(key, fetcher, staleTimeMs !== undefined ? { staleTimeMs } : {});
+        const pending = cache.getPromise(key);
+        if (pending)
+            throw pending;
+    }
     return useMemo(() => ({ ...snapshot, refetch }), [snapshot, refetch]);
 }
 /**

package/react/index.d.ts

@@ -39,4 +39,12 @@ export { HonuaContext, HonuaMapContext } from "./context.js";
 export type { HonuaContextValue, HonuaMapContextValue } from "./context.js";
 export { HonuaQueryCache, stableQueryHash, idleSnapshot } from "./query-cache.js";
 export type { QueryStatus, QuerySnapshot, QueryFetcher } from "./query-cache.js";
+export { HonuaExternalMapContext, HonuaMapProvider, useHonuaMap } from "./external-map.js";
+export type { HonuaMapProviderProps } from "./external-map.js";
+export { useMountedSource } from "./use-mounted-source.js";
+export type { UseMountedSourceOptions, UseMountedSourceResult } from "./use-mounted-source.js";
+export { HonuaSourceLayer } from "./honua-source-layer.js";
+export type { HonuaSourceLayerProps, HonuaSourceRenderer } from "./honua-source-layer.js";
+export { HonuaSelectionContext, HonuaSelectionProvider, HonuaSelectionStore, useHover, useMapHoverBinding, useMapSelectionBinding, useSelection, } from "./selection.js";
+export type { HonuaSelectionProviderProps, HonuaSelectionSnapshot, MapHoverBindingOptions, MapSelectionBindingOptions, UseHoverResult, UseSelectionResult, } from "./selection.js";
 //# sourceMappingURL=index.d.ts.map

package/react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,UAAU,EACV,QAAQ,EACR,eAAe,EACf,aAAa,EACb,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC1F,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC7D,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAE5E,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAClF,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,UAAU,EACV,QAAQ,EACR,eAAe,EACf,aAAa,EACb,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC1F,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC7D,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAE5E,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAClF,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAIjF,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC3F,YAAY,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAE/F,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE1F,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,QAAQ,EACR,kBAAkB,EAClB,sBAAsB,EACtB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,2BAA2B,EAC3B,sBAAsB,EACtB,sBAAsB,EACtB,0BAA0B,EAC1B,cAAc,EACd,kBAAkB,GACnB,MAAM,gBAAgB,CAAC"}

package/react/index.js

@@ -32,3 +32,8 @@ export { HonuaLayer } from "./honua-layer.js";
 export { HonuaPopup } from "./honua-popup.js";
 export { HonuaContext, HonuaMapContext } from "./context.js";
 export { HonuaQueryCache, stableQueryHash, idleSnapshot } from "./query-cache.js";
+// ── React depth pass (issue #498) — all @experimental ─────────────
+export { HonuaExternalMapContext, HonuaMapProvider, useHonuaMap } from "./external-map.js";
+export { useMountedSource } from "./use-mounted-source.js";
+export { HonuaSourceLayer } from "./honua-source-layer.js";
+export { HonuaSelectionContext, HonuaSelectionProvider, HonuaSelectionStore, useHover, useMapHoverBinding, useMapSelectionBinding, useSelection, } from "./selection.js";

package/react/query-cache.d.ts

@@ -27,6 +27,13 @@ export interface QuerySnapshot<T> {
     readonly isLoading: boolean;
     /** True whenever a fetch is in flight, including background refetches. */
     readonly isFetching: boolean;
+    /**
+     * Epoch milliseconds of the last successful fetch, `undefined` until one
+     * resolves. Drives stale-while-revalidate decisions.
+     *
+     * @experimental
+     */
+    readonly dataUpdatedAt?: number;
 }
 /**
  * Returns the shared idle snapshot. Exposed so the SSR / disabled-query paths
@@ -50,11 +57,26 @@ export declare class HonuaQueryCache {
      */
     subscribe(key: string, listener: () => void): () => void;
     /**
-     * Kick off a fetch for `key` only when it has never resolved and is not
-     * already in flight. This is the idempotent entry point hooks call from an
-     * effect; StrictMode's double-invoke therefore does not double-fetch.
+     * Kick off a fetch for `key` when it has never resolved and is not already
+     * in flight. This is the idempotent entry point hooks call from an effect;
+     * StrictMode's double-invoke therefore does not double-fetch.
+     *
+     * With `options.staleTimeMs`, a resolved entry whose data is at least that
+     * old is additionally revalidated in the background (stale-while-revalidate:
+     * the cached data stays served while `isFetching` is true). `0` revalidates
+     * on every ensure; omitted keeps the historical never-revalidate behavior.
+     */
+    ensure<T>(key: string, fetcher: QueryFetcher<T>, options?: {
+        staleTimeMs?: number;
+    }): void;
+    /**
+     * The promise of the in-flight run for `key`, or `undefined` when no fetch
+     * is running. Suspense-mode hooks throw this promise while the first load is
+     * pending; it never rejects (errors land on the snapshot instead).
+     *
+     * @experimental
      */
-    ensure<T>(key: string, fetcher: QueryFetcher<T>): void;
+    getPromise(key: string): Promise<unknown> | undefined;
     /**
      * Force a (re)fetch for `key`, superseding any in-flight request. The last
      * resolved `data` is preserved while the refetch runs.

package/react/query-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-cache.d.ts","sourceRoot":"","sources":["../../../src/react/query-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,gDAAgD;AAChD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnE;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAkBD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,CAElD;AAED,qFAAqF;AACrF,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAElE;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IAEzD,6EAA6E;IAC7E,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC;IAI7C;;;;OAIG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IA+BxD;;;;OAIG;IACH,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI;IAOtD;;;OAGG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI;IA2CnD,sEAAsE;IACtE,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAS7B,gEAAgE;IAChE,KAAK,IAAI,IAAI;IASb,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,KAAK;CAMd;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtD"}
+{"version":3,"file":"query-cache.d.ts","sourceRoot":"","sources":["../../../src/react/query-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,gDAAgD;AAChD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnE;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAoBD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,CAElD;AAED,qFAAqF;AACrF,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAElE;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IAEzD,6EAA6E;IAC7E,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC;IAI7C;;;;OAIG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAgCxD;;;;;;;;;OASG;IACH,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,IAAI;IAgB9F;;;;;;OAMG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,SAAS;IAKrD;;;OAGG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI;IA8CnD,sEAAsE;IACtE,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAS7B,gEAAgE;IAChE,KAAK,IAAI,IAAI;IASb,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,KAAK;CAMd;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtD"}