@honua/react 0.0.20-alpha.0

package/react/honua-layer.d.ts

@@ -0,0 +1,35 @@
+/**
+ * {@link HonuaLayer} — declaratively add a runtime source + layer to the
+ * {@link HonuaMap} it is nested under. Mounting adds the layer (and its source,
+ * if provided); unmounting removes them. StrictMode-safe: the add/remove pair
+ * is balanced across the double-invoked mount.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { RuntimeLayerOrder, RuntimeLayerSpecification, RuntimeSourceSpecification } from "../runtime/index.js";
+/** A source to register alongside a {@link HonuaLayer}. */
+export interface HonuaLayerSource {
+    id: string;
+    spec: RuntimeSourceSpecification;
+}
+/** Props for {@link HonuaLayer}. */
+export interface HonuaLayerProps {
+    /** The MapLibre-shaped runtime layer specification. Its `id` must be stable. */
+    layer: RuntimeLayerSpecification;
+    /**
+     * Optional source to add before the layer. Removed on unmount only if this
+     * component added it (i.e. it was not already present on the runtime).
+     */
+    source?: HonuaLayerSource;
+    /** Insertion order (e.g. `{ beforeId }`). */
+    order?: RuntimeLayerOrder;
+    /** Called if adding/removing the layer or source throws. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Add a layer (and optionally its source) to the enclosing `HonuaMap` runtime.
+ * Must be rendered inside a {@link HonuaMap}; renders nothing itself.
+ */
+export declare function HonuaLayer({ layer, source, order, onError }: HonuaLayerProps): ReactNode;
+//# sourceMappingURL=honua-layer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"honua-layer.d.ts","sourceRoot":"","sources":["../../../src/react/honua-layer.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAa,MAAM,OAAO,CAAC;AAElD,OAAO,KAAK,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAGpH,2DAA2D;AAC3D,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,0BAA0B,CAAC;CAClC;AAED,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,KAAK,EAAE,yBAAyB,CAAC;IACjC;;;OAGG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,6CAA6C;IAC7C,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,4DAA4D;IAC5D,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,eAAe,GAAG,SAAS,CAgCxF"}

package/react/honua-layer.js

@@ -0,0 +1,47 @@
+/**
+ * {@link HonuaLayer} — declaratively add a runtime source + layer to the
+ * {@link HonuaMap} it is nested under. Mounting adds the layer (and its source,
+ * if provided); unmounting removes them. StrictMode-safe: the add/remove pair
+ * is balanced across the double-invoked mount.
+ *
+ * @module
+ */
+import { useEffect } from "react";
+import { useMapRuntime } from "./hooks.js";
+/**
+ * Add a layer (and optionally its source) to the enclosing `HonuaMap` runtime.
+ * Must be rendered inside a {@link HonuaMap}; renders nothing itself.
+ */
+export function HonuaLayer({ layer, source, order, onError }) {
+    const runtime = useMapRuntime();
+    const layerId = layer.id;
+    const sourceId = source?.id;
+    useEffect(() => {
+        if (!runtime)
+            return;
+        let addedSource = false;
+        try {
+            if (source && !runtime.map.getSource?.(source.id)) {
+                runtime.addSource(source.id, source.spec);
+                addedSource = true;
+            }
+            runtime.addLayer(layer, order);
+        }
+        catch (error) {
+            onError?.(error);
+        }
+        return () => {
+            try {
+                runtime.removeLayer(layerId);
+                if (addedSource && sourceId) {
+                    runtime.removeSource(sourceId);
+                }
+            }
+            catch (error) {
+                onError?.(error);
+            }
+        };
+        // biome-ignore lint/correctness/useExhaustiveDependencies: re-run on runtime + identity of layer/source/order; onError is a stable-intent callback.
+    }, [runtime, layer, source, order, layerId, sourceId]);
+    return null;
+}

package/react/honua-map.d.ts

@@ -0,0 +1,83 @@
+/**
+ * {@link HonuaMap} — a React component that owns a {@link HonuaMapRuntime}
+ * lifecycle over a MapLibre GL map. It can create and own the map itself, or
+ * attach to an externally-owned map instance (the `@vis.gl/react-maplibre`
+ * interop pattern). Children ({@link HonuaLayer} / {@link HonuaPopup}) reach the
+ * runtime through context.
+ *
+ * SSR-safe: `maplibre-gl` is only imported (dynamically) inside a mount effect,
+ * never at module load. StrictMode-safe: the mount effect fully disposes the
+ * runtime and removes any owned map on cleanup, so a double-invoked mount never
+ * leaks a runtime or a WebGL context.
+ *
+ * @module
+ */
+import { type CSSProperties, type ReactNode } from "react";
+import type { HonuaMapPackage, HonuaMapRuntime, LoadMapPackageOptions, MaplibreMap } from "../runtime/index.js";
+/** Options accepted by the `maplibre-gl` `Map` constructor that `HonuaMap` uses. */
+export interface MapLibreMapOptions {
+    container: string | HTMLElement;
+    style: unknown;
+    center?: [number, number];
+    zoom?: number;
+    [key: string]: unknown;
+}
+/**
+ * The shape of the `maplibre-gl` module `HonuaMap` needs when it owns the map.
+ * Pass your imported `maplibre-gl` namespace as {@link HonuaMapProps.mapLibre},
+ * or let `HonuaMap` dynamically `import("maplibre-gl")`.
+ */
+export interface MapLibreGlModule {
+    Map: new (options: MapLibreMapOptions) => MaplibreMap & {
+        remove(): void;
+    };
+    Popup: new (options?: Record<string, unknown>) => unknown;
+}
+/** Props for {@link HonuaMap}. */
+export interface HonuaMapProps {
+    /** The `MapPackage` to compose onto the map. */
+    package: HonuaMapPackage;
+    /**
+     * Attach to an existing, externally-owned map instead of creating one. When
+     * set, `HonuaMap` never removes the map on unmount (the owner is responsible)
+     * — it only disposes the runtime.
+     */
+    map?: MaplibreMap;
+    /**
+     * The `maplibre-gl` module. Provide it to avoid a dynamic import (and to pin
+     * the exact version). Ignored when {@link map} is supplied.
+     */
+    mapLibre?: MapLibreGlModule;
+    /**
+     * Extra options merged into the `maplibre-gl` `Map` constructor when
+     * `HonuaMap` owns the map (`container` and `style` are managed for you).
+     */
+    mapOptions?: Partial<Omit<MapLibreMapOptions, "container">>;
+    /**
+     * Extra options forwarded to `loadMapPackage`. `client` is taken from the
+     * provider; a `popupFactory` is defaulted from the maplibre module when one
+     * is available so {@link HonuaPopup} works out of the box.
+     */
+    loadOptions?: Omit<LoadMapPackageOptions, "client">;
+    /** Called once the runtime is ready. */
+    onRuntime?: (runtime: HonuaMapRuntime) => void;
+    /** Called if map creation or package loading fails. */
+    onError?: (error: unknown) => void;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}
+/**
+ * Render a Honua-composed MapLibre map.
+ *
+ * @example
+ * ```tsx
+ * <HonuaMap package={mapPackage} style={{ height: 480 }}>
+ *   <HonuaLayer layer={{ id: "sites", type: "circle", source: "sites", paint: { "circle-radius": 6 } }}
+ *               source={{ id: "sites", spec: { type: "geojson", data: sitesGeoJson } }} />
+ *   <HonuaPopup layer="sites" binding={{ sourceId: "sites", title: "Site" }} />
+ * </HonuaMap>
+ * ```
+ */
+export declare function HonuaMap(props: HonuaMapProps): ReactNode;
+//# sourceMappingURL=honua-map.d.ts.map

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

@@ -0,0 +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"}

package/react/honua-map.js

@@ -0,0 +1,109 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * {@link HonuaMap} — a React component that owns a {@link HonuaMapRuntime}
+ * lifecycle over a MapLibre GL map. It can create and own the map itself, or
+ * attach to an externally-owned map instance (the `@vis.gl/react-maplibre`
+ * interop pattern). Children ({@link HonuaLayer} / {@link HonuaPopup}) reach the
+ * runtime through context.
+ *
+ * SSR-safe: `maplibre-gl` is only imported (dynamically) inside a mount effect,
+ * never at module load. StrictMode-safe: the mount effect fully disposes the
+ * runtime and removes any owned map on cleanup, so a double-invoked mount never
+ * leaks a runtime or a WebGL context.
+ *
+ * @module
+ */
+import { useEffect, useRef, useState } from "react";
+import { loadMapPackage } from "../runtime/index.js";
+import { useHonuaClient } from "./hooks.js";
+import { HonuaMapContext } from "./context.js";
+const EMPTY_STYLE = { version: 8, sources: {}, layers: [] };
+/**
+ * Render a Honua-composed MapLibre map.
+ *
+ * @example
+ * ```tsx
+ * <HonuaMap package={mapPackage} style={{ height: 480 }}>
+ *   <HonuaLayer layer={{ id: "sites", type: "circle", source: "sites", paint: { "circle-radius": 6 } }}
+ *               source={{ id: "sites", spec: { type: "geojson", data: sitesGeoJson } }} />
+ *   <HonuaPopup layer="sites" binding={{ sourceId: "sites", title: "Site" }} />
+ * </HonuaMap>
+ * ```
+ */
+export function HonuaMap(props) {
+    const { package: mapPackage, map: externalMap, mapLibre, mapOptions, loadOptions, onRuntime, onError, className, style, children, } = props;
+    const client = useHonuaClient();
+    const containerRef = useRef(null);
+    const [contextValue, setContextValue] = useState({ runtime: null, map: null });
+    // The package reference last handed to load/updatePackage — lets us route
+    // subsequent package changes through `updatePackage` instead of reloading.
+    const appliedPackageRef = useRef(null);
+    useEffect(() => {
+        let cancelled = false;
+        let runtime = null;
+        let ownedMap = null;
+        const start = async () => {
+            let map = externalMap ?? null;
+            let gl = mapLibre;
+            if (!map) {
+                const container = containerRef.current;
+                if (!container)
+                    return;
+                gl = mapLibre ?? (await import("maplibre-gl")).default;
+                if (cancelled)
+                    return;
+                ownedMap = new gl.Map({
+                    container,
+                    style: EMPTY_STYLE,
+                    ...mapOptions,
+                });
+                map = ownedMap;
+            }
+            // Default a popup factory from the maplibre module (when we have it) so
+            // HonuaPopup works without extra wiring.
+            const glModule = gl;
+            const popupFactory = loadOptions?.popupFactory ?? (glModule ? (() => new glModule.Popup()) : undefined);
+            const loaded = await loadMapPackage(mapPackage, map, {
+                ...loadOptions,
+                client,
+                popupFactory,
+            });
+            if (cancelled) {
+                loaded.dispose();
+                ownedMap?.remove();
+                return;
+            }
+            runtime = loaded;
+            appliedPackageRef.current = mapPackage;
+            setContextValue({ runtime: loaded, map });
+            onRuntime?.(loaded);
+        };
+        start().catch((error) => {
+            if (cancelled)
+                return;
+            onError?.(error);
+        });
+        return () => {
+            cancelled = true;
+            runtime?.dispose();
+            ownedMap?.remove();
+            appliedPackageRef.current = null;
+            setContextValue({ runtime: null, map: null });
+        };
+        // Recreate only when the client, external map, or maplibre module changes.
+        // Package-content changes are handled by the effect below via updatePackage.
+        // biome-ignore lint/correctness/useExhaustiveDependencies: intentionally excludes mapPackage/options to avoid map re-creation.
+    }, [client, externalMap, mapLibre]);
+    // Route package changes to updatePackage without tearing down the map.
+    useEffect(() => {
+        const runtime = contextValue.runtime;
+        if (!runtime)
+            return;
+        if (appliedPackageRef.current === mapPackage)
+            return;
+        appliedPackageRef.current = mapPackage;
+        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] }));
+}

package/react/honua-popup.d.ts

@@ -0,0 +1,26 @@
+/**
+ * {@link HonuaPopup} — declaratively bind a runtime popup to a layer inside a
+ * {@link HonuaMap}. The binding is removed on unmount (StrictMode-safe).
+ *
+ * Requires the enclosing `HonuaMap` to have a `popupFactory` — `HonuaMap`
+ * defaults one from its maplibre module, so this works out of the box.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { HonuaMapPackagePopupBinding } from "../runtime/index.js";
+/** Props for {@link HonuaPopup}. */
+export interface HonuaPopupProps {
+    /** The layer id whose feature clicks open the popup. */
+    layer: string;
+    /** Optional popup binding (source id, title, template, field). */
+    binding?: HonuaMapPackagePopupBinding;
+    /** Called if binding the popup throws (e.g. no `popupFactory` configured). */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Bind a click-to-open popup to a layer in the enclosing `HonuaMap`. Must be
+ * rendered inside a {@link HonuaMap}; renders nothing itself.
+ */
+export declare function HonuaPopup({ layer, binding, onError }: HonuaPopupProps): ReactNode;
+//# sourceMappingURL=honua-popup.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"honua-popup.d.ts","sourceRoot":"","sources":["../../../src/react/honua-popup.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAa,MAAM,OAAO,CAAC;AAElD,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAGvE,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,OAAO,CAAC,EAAE,2BAA2B,CAAC;IACtC,8EAA8E;IAC9E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,eAAe,GAAG,SAAS,CAkBlF"}

package/react/honua-popup.js

@@ -0,0 +1,34 @@
+/**
+ * {@link HonuaPopup} — declaratively bind a runtime popup to a layer inside a
+ * {@link HonuaMap}. The binding is removed on unmount (StrictMode-safe).
+ *
+ * Requires the enclosing `HonuaMap` to have a `popupFactory` — `HonuaMap`
+ * defaults one from its maplibre module, so this works out of the box.
+ *
+ * @module
+ */
+import { useEffect } from "react";
+import { useMapRuntime } from "./hooks.js";
+/**
+ * Bind a click-to-open popup to a layer in the enclosing `HonuaMap`. Must be
+ * rendered inside a {@link HonuaMap}; renders nothing itself.
+ */
+export function HonuaPopup({ layer, binding, onError }) {
+    const runtime = useMapRuntime();
+    useEffect(() => {
+        if (!runtime)
+            return;
+        let handle;
+        try {
+            handle = runtime.bindPopup(layer, binding);
+        }
+        catch (error) {
+            onError?.(error);
+        }
+        return () => {
+            handle?.remove();
+        };
+        // biome-ignore lint/correctness/useExhaustiveDependencies: re-bind on runtime + layer + binding identity; onError is a stable-intent callback.
+    }, [runtime, layer, binding]);
+    return null;
+}

package/react/hooks.d.ts

@@ -0,0 +1,127 @@
+/**
+ * `@honua/react` hooks: {@link useHonuaClient}, {@link useDataset},
+ * {@link useQuery}, {@link useCapabilities}, {@link useMapRuntime}, and
+ * {@link useRealtime}.
+ *
+ * All data hooks are AbortController-wired and StrictMode-safe, and expose
+ * `loading` / `error` / `data` state. Query results are referentially stable
+ * until the underlying data changes (NFR-001) because reads go through
+ * `useSyncExternalStore` over the provider's {@link HonuaQueryCache}.
+ *
+ * @module
+ */
+import type { CapabilityPolicy, Dataset, DatasetId, Query, Result, Source, SourceDescriptor, SourceResolver } from "../contract/index.js";
+import type { HonuaClient } from "../core/client.js";
+import type { HonuaCompatibilityRequest, HonuaServerCompatibility } from "../core/types.js";
+import type { HonuaMapRuntime } from "../runtime/index.js";
+import { type HonuaQueryCache, type QuerySnapshot } from "./query-cache.js";
+/**
+ * Access the {@link HonuaClient} published by the nearest {@link HonuaProvider}.
+ *
+ * @throws if called outside a `HonuaProvider`.
+ */
+export declare function useHonuaClient(): HonuaClient;
+/**
+ * Access the provider's {@link HonuaQueryCache}. Rarely needed directly;
+ * exposed for advanced invalidation (`cache.invalidate(key)` / `cache.clear()`).
+ */
+export declare function useHonuaQueryCache(): HonuaQueryCache;
+/** Options accepted by {@link useDataset}. `client` is taken from context. */
+export interface UseDatasetOptions {
+    id: DatasetId;
+    sources: ReadonlyArray<SourceDescriptor>;
+    capabilityPolicy?: CapabilityPolicy;
+    skipCompatibilityCheck?: boolean;
+    resolveSource?: SourceResolver;
+}
+/**
+ * Build a memoized {@link Dataset} bound to the provider's client. The dataset
+ * identity is stable until its `id`, source descriptors, or policy change, so
+ * it is safe to pass its sources into {@link useQuery} across re-renders.
+ *
+ * @example
+ * ```tsx
+ * const dataset = useDataset({
+ *   id: "incidents",
+ *   sources: [{ id: "incidents", protocol: "geoservices-feature-service",
+ *     locator: { url, serviceId: "incidents", layerId: 0 },
+ *     capabilities: PROTOCOL_DEFAULT_CAPABILITIES["geoservices-feature-service"] }],
+ * });
+ * ```
+ */
+export declare function useDataset(options: UseDatasetOptions): Dataset;
+/** Options for {@link useQuery}. */
+export interface UseQueryOptions {
+    /** When `false`, the query is not executed and stays in `idle`. Default `true`. */
+    enabled?: boolean;
+    /** Use `source.queryAll()` (drain every page) instead of a single page. */
+    drainAllPages?: boolean;
+}
+/** Result of {@link useQuery}: a stable snapshot plus a `refetch` trigger. */
+export interface UseQueryResult<T> extends QuerySnapshot<Result<T>> {
+    /** Force a fresh fetch, superseding any in-flight request. */
+    refetch: () => void;
+}
+/**
+ * Execute a contract {@link Query} against a {@link Source} with loading /
+ * error / data state. Results are cached per `(source, query-hash)` inside the
+ * provider and are referentially stable until the data changes. The request is
+ * aborted when the component unmounts or the query key changes; superseded
+ * responses are ignored (no races).
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading, error, refetch } = useQuery(
+ *   dataset.source("incidents"),
+ *   { where: "STATUS = 'OPEN'", returnGeometry: true },
+ * );
+ * ```
+ */
+export declare function useQuery<T = Record<string, unknown>>(source: Source<T> | undefined | null, query?: Query<T>, options?: UseQueryOptions): UseQueryResult<T>;
+/** Options for {@link useCapabilities}. */
+export interface UseCapabilitiesOptions {
+    /** When `false`, capabilities are not fetched. Default `true`. */
+    enabled?: boolean;
+    /** Forwarded to `client.getCompatibility` (e.g. `{ refresh: true }`). */
+    request?: Omit<HonuaCompatibilityRequest, "signal">;
+}
+/** Result of {@link useCapabilities}. */
+export interface UseCapabilitiesResult extends QuerySnapshot<HonuaServerCompatibility> {
+    refetch: () => void;
+}
+/**
+ * Fetch the Honua server's capability / compatibility descriptor
+ * (`serverVersion`, `releaseChannel`, feature flags) with loading / error /
+ * data state. Cached per-request inside the provider.
+ */
+export declare function useCapabilities(options?: UseCapabilitiesOptions): UseCapabilitiesResult;
+/**
+ * Access the {@link HonuaMapRuntime} owned by the nearest {@link HonuaMap}.
+ * Returns `null` until the map has finished loading its package, and when
+ * called outside a `HonuaMap`.
+ */
+export declare function useMapRuntime(): HonuaMapRuntime | null;
+/** A realtime subscription cleanup handle, in any of the SDK's shapes. */
+export type RealtimeCleanup = (() => void) | {
+    close(): void;
+} | {
+    remove(): void;
+} | {
+    unsubscribe(): void;
+};
+/**
+ * Open a realtime subscription for the lifetime of the component and tear it
+ * down on unmount (StrictMode-safe: the effect's cleanup runs between the
+ * double-invoked mounts, so no duplicate subscriptions leak).
+ *
+ * `factory` should open the subscription and return its cleanup handle. It is
+ * re-run whenever `deps` change. Works with the SDK realtime store
+ * (`store.connect(...)` returns `{ close() }`) or any `() => void` unsubscribe.
+ *
+ * @example
+ * ```tsx
+ * useRealtime(() => store.connect(transport, request), [transport, request]);
+ * ```
+ */
+export declare function useRealtime(factory: (() => RealtimeCleanup | undefined) | null | undefined, deps?: readonly unknown[]): void;
+//# sourceMappingURL=hooks.d.ts.map

package/react/hooks.d.ts.map

@@ -0,0 +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"}