@honua/react 0.0.20-alpha.0

package/react/hooks.js

@@ -0,0 +1,206 @@
+/**
+ * `@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 { useCallback, useContext, useDebugValue, useEffect, useMemo, useSyncExternalStore } from "react";
+import { createDataset } from "../contract/index.js";
+import { HonuaContext, HonuaMapContext } from "./context.js";
+import { idleSnapshot, stableQueryHash } from "./query-cache.js";
+function useHonuaContext(hookName) {
+    const value = useContext(HonuaContext);
+    if (value === null) {
+        throw new Error(`${hookName} must be used within a <HonuaProvider>.`);
+    }
+    return value;
+}
+/**
+ * Access the {@link HonuaClient} published by the nearest {@link HonuaProvider}.
+ *
+ * @throws if called outside a `HonuaProvider`.
+ */
+export function useHonuaClient() {
+    return useHonuaContext("useHonuaClient").client;
+}
+/**
+ * Access the provider's {@link HonuaQueryCache}. Rarely needed directly;
+ * exposed for advanced invalidation (`cache.invalidate(key)` / `cache.clear()`).
+ */
+export function useHonuaQueryCache() {
+    return useHonuaContext("useHonuaQueryCache").cache;
+}
+function datasetSignature(options) {
+    const descriptors = options.sources
+        .map((descriptor) => stableQueryHash({ ...descriptor, capabilities: descriptor.capabilities }))
+        .join("|");
+    return [
+        options.id,
+        options.capabilityPolicy ?? "strict",
+        options.skipCompatibilityCheck ? "1" : "0",
+        descriptors,
+    ].join("::");
+}
+/**
+ * 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 function useDataset(options) {
+    const client = useHonuaClient();
+    const signature = datasetSignature(options);
+    // `signature` captures id/sources/policy; `resolveSource` is a function
+    // identity folded in so a new resolver rebuilds the dataset. Callers should
+    // memoize `resolveSource` to keep the dataset stable.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: options.* are captured through `signature`.
+    const dataset = useMemo(() => createDataset({
+        id: options.id,
+        client,
+        sources: options.sources,
+        capabilityPolicy: options.capabilityPolicy,
+        skipCompatibilityCheck: options.skipCompatibilityCheck,
+        resolveSource: options.resolveSource,
+    }), [client, signature, options.resolveSource]);
+    useDebugValue(dataset.id);
+    return dataset;
+}
+/**
+ * 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 function useQuery(source, query, options = {}) {
+    const { cache } = useHonuaContext("useQuery");
+    const enabled = options.enabled ?? true;
+    const drainAllPages = options.drainAllPages ?? false;
+    const sourceId = source?.descriptor.id;
+    const queryHash = stableQueryHash(query ?? {});
+    // `key` (and thus every effect below) intentionally re-derives from the
+    // stable `queryHash` rather than the `query` object identity, so an inline
+    // query literal does not thrash the cache.
+    const key = useMemo(() => {
+        if (!source || sourceId === undefined || !enabled)
+            return null;
+        return `query::${String(sourceId)}::${drainAllPages ? "all" : "page"}::${queryHash}`;
+    }, [source, sourceId, enabled, drainAllPages, queryHash]);
+    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());
+    // 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]);
+    // 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]);
+    useDebugValue(snapshot.status);
+    return useMemo(() => ({ ...snapshot, refetch }), [snapshot, refetch]);
+}
+/**
+ * Fetch the Honua server's capability / compatibility descriptor
+ * (`serverVersion`, `releaseChannel`, feature flags) with loading / error /
+ * data state. Cached per-request inside the provider.
+ */
+export function useCapabilities(options = {}) {
+    const { client, cache } = useHonuaContext("useCapabilities");
+    const enabled = options.enabled ?? true;
+    const requestHash = stableQueryHash(options.request ?? {});
+    const key = useMemo(() => (enabled ? `capabilities::${requestHash}` : null), [enabled, requestHash]);
+    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());
+    // biome-ignore lint/correctness/useExhaustiveDependencies: request identity is captured through `requestHash`.
+    const fetcher = useCallback((signal) => client.getCompatibility({ ...options.request, signal }), [client, requestHash]);
+    useEffect(() => {
+        if (!key)
+            return;
+        cache.ensure(key, fetcher);
+    }, [cache, key, fetcher]);
+    const refetch = useCallback(() => {
+        if (!key)
+            return;
+        cache.run(key, fetcher);
+    }, [cache, key, fetcher]);
+    useDebugValue(snapshot.status);
+    return useMemo(() => ({ ...snapshot, refetch }), [snapshot, refetch]);
+}
+/**
+ * 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 function useMapRuntime() {
+    return useContext(HonuaMapContext)?.runtime ?? null;
+}
+/**
+ * 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 function useRealtime(factory, deps = []) {
+    // biome-ignore lint/correctness/useExhaustiveDependencies: the caller-supplied dependency list controls re-subscription.
+    useEffect(() => {
+        if (!factory)
+            return;
+        const handle = factory();
+        return () => {
+            runCleanup(handle);
+        };
+    }, deps);
+}
+function runCleanup(handle) {
+    if (!handle)
+        return;
+    if (typeof handle === "function") {
+        handle();
+    }
+    else if ("close" in handle) {
+        handle.close();
+    }
+    else if ("remove" in handle) {
+        handle.remove();
+    }
+    else {
+        handle.unsubscribe();
+    }
+}

package/react/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `@honua/react` — idiomatic React bindings for the Honua SDK: a provider,
+ * data hooks, and declarative map components over the framework-neutral
+ * `@honua/sdk-js` core.
+ *
+ * The core SDK stays React-free; this entry point is the only place React is
+ * imported. It is SSR-safe (no `window`/`document` access at import time) and
+ * StrictMode-safe under React 18 and 19.
+ *
+ * @example
+ * ```tsx
+ * import { HonuaClient } from "@honua/sdk-js/honua";
+ * import { HonuaProvider, useDataset, useQuery } from "@honua/react";
+ *
+ * const client = new HonuaClient({ baseUrl: "https://honua.example.com" });
+ *
+ * function App() {
+ *   return (
+ *     <HonuaProvider client={client}>
+ *       <Incidents />
+ *     </HonuaProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { HonuaProvider } from "./provider.js";
+export type { HonuaProviderProps } from "./provider.js";
+export { useHonuaClient, useHonuaQueryCache, useDataset, useQuery, useCapabilities, useMapRuntime, useRealtime, } from "./hooks.js";
+export type { UseDatasetOptions, UseQueryOptions, UseQueryResult, UseCapabilitiesOptions, UseCapabilitiesResult, RealtimeCleanup, } from "./hooks.js";
+export { HonuaMap } from "./honua-map.js";
+export type { HonuaMapProps, MapLibreGlModule, MapLibreMapOptions } from "./honua-map.js";
+export { HonuaLayer } from "./honua-layer.js";
+export type { HonuaLayerProps, HonuaLayerSource } from "./honua-layer.js";
+export { HonuaPopup } from "./honua-popup.js";
+export type { HonuaPopupProps } from "./honua-popup.js";
+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";
+//# sourceMappingURL=index.d.ts.map

package/react/index.d.ts.map

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

package/react/index.js

@@ -0,0 +1,34 @@
+/**
+ * `@honua/react` — idiomatic React bindings for the Honua SDK: a provider,
+ * data hooks, and declarative map components over the framework-neutral
+ * `@honua/sdk-js` core.
+ *
+ * The core SDK stays React-free; this entry point is the only place React is
+ * imported. It is SSR-safe (no `window`/`document` access at import time) and
+ * StrictMode-safe under React 18 and 19.
+ *
+ * @example
+ * ```tsx
+ * import { HonuaClient } from "@honua/sdk-js/honua";
+ * import { HonuaProvider, useDataset, useQuery } from "@honua/react";
+ *
+ * const client = new HonuaClient({ baseUrl: "https://honua.example.com" });
+ *
+ * function App() {
+ *   return (
+ *     <HonuaProvider client={client}>
+ *       <Incidents />
+ *     </HonuaProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { HonuaProvider } from "./provider.js";
+export { useHonuaClient, useHonuaQueryCache, useDataset, useQuery, useCapabilities, useMapRuntime, useRealtime, } from "./hooks.js";
+export { HonuaMap } from "./honua-map.js";
+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";

package/react/provider.d.ts

@@ -0,0 +1,36 @@
+/**
+ * {@link HonuaProvider} — the root of every `@honua/react` tree. Publishes an
+ * active {@link HonuaClient} plus a per-provider {@link HonuaQueryCache} to the
+ * hooks and map components below it.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { HonuaClient } from "../core/client.js";
+import { HonuaQueryCache } from "./query-cache.js";
+/** Props for {@link HonuaProvider}. */
+export interface HonuaProviderProps {
+    /** The client every descendant hook/component queries through. */
+    client: HonuaClient;
+    /**
+     * Optional externally-owned query cache. Supply one to share cached results
+     * across providers or to pre-seed a cache in tests; omit to let the provider
+     * own a fresh, session-scoped cache.
+     */
+    cache?: HonuaQueryCache;
+    children?: ReactNode;
+}
+/**
+ * Wrap an application (or subtree) to make a `HonuaClient` available to the
+ * `@honua/react` hooks and map components.
+ *
+ * @example
+ * ```tsx
+ * const client = new HonuaClient({ baseUrl: "https://honua.example.com" });
+ * <HonuaProvider client={client}>
+ *   <App />
+ * </HonuaProvider>
+ * ```
+ */
+export declare function HonuaProvider({ client, cache, children }: HonuaProviderProps): ReactNode;
+//# sourceMappingURL=provider.d.ts.map

package/react/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../src/react/provider.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAmB,MAAM,OAAO,CAAC;AAExD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,MAAM,EAAE,WAAW,CAAC;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,kBAAkB,GAAG,SAAS,CAgBxF"}

package/react/provider.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * {@link HonuaProvider} — the root of every `@honua/react` tree. Publishes an
+ * active {@link HonuaClient} plus a per-provider {@link HonuaQueryCache} to the
+ * hooks and map components below it.
+ *
+ * @module
+ */
+import { useMemo, useRef } from "react";
+import { HonuaContext } from "./context.js";
+import { HonuaQueryCache } from "./query-cache.js";
+/**
+ * Wrap an application (or subtree) to make a `HonuaClient` available to the
+ * `@honua/react` hooks and map components.
+ *
+ * @example
+ * ```tsx
+ * const client = new HonuaClient({ baseUrl: "https://honua.example.com" });
+ * <HonuaProvider client={client}>
+ *   <App />
+ * </HonuaProvider>
+ * ```
+ */
+export function HonuaProvider({ client, cache, children }) {
+    // Own a stable cache for the provider's lifetime unless the caller supplies
+    // one. `useRef` keeps the same instance across re-renders and StrictMode's
+    // double-invoke of render.
+    const ownedCacheRef = useRef(null);
+    if (ownedCacheRef.current === null) {
+        ownedCacheRef.current = new HonuaQueryCache();
+    }
+    const activeCache = cache ?? ownedCacheRef.current;
+    const value = useMemo(() => ({ client, cache: activeCache }), [client, activeCache]);
+    return _jsx(HonuaContext.Provider, { value: value, children: children });
+}

package/react/query-cache.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Framework-neutral query cache used by the `@honua/react` hooks. Lives
+ * outside React so it can back `useSyncExternalStore` (referentially stable
+ * snapshots, StrictMode-safe subscriptions) and be shared across every hook
+ * mounted under a single {@link HonuaProvider}.
+ *
+ * The cache keys results per `(source, query-hash)` string. It never persists
+ * across sessions and holds no cross-`HonuaProvider` state: each provider owns
+ * one cache instance.
+ *
+ * @module
+ */
+/** Lifecycle state of a single cached query. */
+export type QueryStatus = "idle" | "loading" | "success" | "error";
+/**
+ * Immutable snapshot of a cached query. The same object reference is returned
+ * from {@link HonuaQueryCache.getSnapshot} until the underlying state changes,
+ * which is what gives hooks their referential stability (NFR-001).
+ */
+export interface QuerySnapshot<T> {
+    readonly status: QueryStatus;
+    /** Last resolved value. Preserved across background refetches. */
+    readonly data: T | undefined;
+    /** Last rejection reason, cleared on the next successful fetch. */
+    readonly error: unknown;
+    /** True only while the first fetch (no data yet) is in flight. */
+    readonly isLoading: boolean;
+    /** True whenever a fetch is in flight, including background refetches. */
+    readonly isFetching: boolean;
+}
+/**
+ * Returns the shared idle snapshot. Exposed so the SSR / disabled-query paths
+ * can hand back a stable reference without allocating.
+ */
+export declare function idleSnapshot<T>(): QuerySnapshot<T>;
+/** A fetcher receives the cache-owned `AbortSignal` for cooperative cancellation. */
+export type QueryFetcher<T> = (signal: AbortSignal) => Promise<T>;
+/**
+ * Per-`HonuaProvider` cache of query results. Not a React construct; it is
+ * driven by the hooks via {@link subscribe} / {@link getSnapshot} / {@link ensure}.
+ */
+export declare class HonuaQueryCache {
+    private readonly entries;
+    /** Read the current snapshot for `key`; a stable idle snapshot if unseen. */
+    getSnapshot<T>(key: string): QuerySnapshot<T>;
+    /**
+     * Subscribe `listener` to changes for `key`. When the final listener for a
+     * key unsubscribes and a fetch is still in flight, the fetch is aborted so
+     * unmounting the last consumer cancels the underlying request.
+     */
+    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.
+     */
+    ensure<T>(key: string, fetcher: QueryFetcher<T>): void;
+    /**
+     * Force a (re)fetch for `key`, superseding any in-flight request. The last
+     * resolved `data` is preserved while the refetch runs.
+     */
+    run<T>(key: string, fetcher: QueryFetcher<T>): void;
+    /** Drop the cached result for `key` and abort any in-flight fetch. */
+    invalidate(key: string): void;
+    /** Abort every in-flight fetch and clear all cached results. */
+    clear(): void;
+    private entryFor;
+    private write;
+}
+/**
+ * Deterministic, key-order-independent hash of a query-like object. Used to
+ * build the `(source, query-hash)` cache key. `AbortSignal` and `undefined`
+ * values are ignored so they do not perturb the identity of a query.
+ */
+export declare function stableQueryHash(value: unknown): string;
+//# sourceMappingURL=query-cache.d.ts.map

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

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

package/react/query-cache.js

@@ -0,0 +1,188 @@
+/**
+ * Framework-neutral query cache used by the `@honua/react` hooks. Lives
+ * outside React so it can back `useSyncExternalStore` (referentially stable
+ * snapshots, StrictMode-safe subscriptions) and be shared across every hook
+ * mounted under a single {@link HonuaProvider}.
+ *
+ * The cache keys results per `(source, query-hash)` string. It never persists
+ * across sessions and holds no cross-`HonuaProvider` state: each provider owns
+ * one cache instance.
+ *
+ * @module
+ */
+const IDLE_SNAPSHOT = Object.freeze({
+    status: "idle",
+    data: undefined,
+    error: undefined,
+    isLoading: false,
+    isFetching: false,
+});
+/**
+ * Returns the shared idle snapshot. Exposed so the SSR / disabled-query paths
+ * can hand back a stable reference without allocating.
+ */
+export function idleSnapshot() {
+    return IDLE_SNAPSHOT;
+}
+/**
+ * Per-`HonuaProvider` cache of query results. Not a React construct; it is
+ * driven by the hooks via {@link subscribe} / {@link getSnapshot} / {@link ensure}.
+ */
+export class HonuaQueryCache {
+    entries = new Map();
+    /** Read the current snapshot for `key`; a stable idle snapshot if unseen. */
+    getSnapshot(key) {
+        return (this.entries.get(key)?.snapshot ?? IDLE_SNAPSHOT);
+    }
+    /**
+     * Subscribe `listener` to changes for `key`. When the final listener for a
+     * key unsubscribes and a fetch is still in flight, the fetch is aborted so
+     * unmounting the last consumer cancels the underlying request.
+     */
+    subscribe(key, listener) {
+        const entry = this.entryFor(key);
+        entry.listeners.add(listener);
+        return () => {
+            entry.listeners.delete(listener);
+            if (entry.listeners.size === 0 && entry.controller) {
+                // Last consumer left while a fetch was in flight: abort it and
+                // invalidate the run so its (now irrelevant) settlement is ignored.
+                entry.controller.abort();
+                entry.controller = undefined;
+                entry.token += 1;
+                // If nothing had resolved yet, drop back to `idle` so the next
+                // subscriber (e.g. a StrictMode remount) re-fetches from a clean
+                // state instead of being stuck on a `loading` snapshot that will
+                // never settle. A previously-resolved value is preserved.
+                if (entry.snapshot.status === "loading") {
+                    entry.snapshot =
+                        entry.snapshot.data === undefined
+                            ? IDLE_SNAPSHOT
+                            : {
+                                status: "success",
+                                data: entry.snapshot.data,
+                                error: undefined,
+                                isLoading: false,
+                                isFetching: false,
+                            };
+                }
+            }
+        };
+    }
+    /**
+     * 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.
+     */
+    ensure(key, fetcher) {
+        const entry = this.entryFor(key);
+        if (entry.snapshot.status === "idle") {
+            this.run(key, fetcher);
+        }
+    }
+    /**
+     * Force a (re)fetch for `key`, superseding any in-flight request. The last
+     * resolved `data` is preserved while the refetch runs.
+     */
+    run(key, fetcher) {
+        const entry = this.entryFor(key);
+        entry.controller?.abort();
+        const controller = new AbortController();
+        const token = entry.token + 1;
+        entry.token = token;
+        entry.controller = controller;
+        this.write(entry, {
+            status: "loading",
+            data: entry.snapshot.data,
+            error: undefined,
+            isLoading: entry.snapshot.data === undefined,
+            isFetching: true,
+        });
+        fetcher(controller.signal).then((value) => {
+            if (entry.token !== token)
+                return;
+            entry.controller = undefined;
+            this.write(entry, {
+                status: "success",
+                data: value,
+                error: undefined,
+                isLoading: false,
+                isFetching: false,
+            });
+        }, (error) => {
+            if (entry.token !== token || controller.signal.aborted)
+                return;
+            entry.controller = undefined;
+            this.write(entry, {
+                status: "error",
+                data: entry.snapshot.data,
+                error,
+                isLoading: false,
+                isFetching: false,
+            });
+        });
+    }
+    /** Drop the cached result for `key` and abort any in-flight fetch. */
+    invalidate(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return;
+        entry.controller?.abort();
+        entry.controller = undefined;
+        entry.token += 1;
+        this.write(entry, IDLE_SNAPSHOT);
+    }
+    /** Abort every in-flight fetch and clear all cached results. */
+    clear() {
+        for (const entry of this.entries.values()) {
+            entry.controller?.abort();
+            entry.controller = undefined;
+            entry.token += 1;
+        }
+        this.entries.clear();
+    }
+    entryFor(key) {
+        let entry = this.entries.get(key);
+        if (!entry) {
+            entry = { snapshot: IDLE_SNAPSHOT, listeners: new Set(), controller: undefined, token: 0 };
+            this.entries.set(key, entry);
+        }
+        return entry;
+    }
+    write(entry, snapshot) {
+        entry.snapshot = snapshot;
+        for (const listener of entry.listeners) {
+            listener();
+        }
+    }
+}
+/**
+ * Deterministic, key-order-independent hash of a query-like object. Used to
+ * build the `(source, query-hash)` cache key. `AbortSignal` and `undefined`
+ * values are ignored so they do not perturb the identity of a query.
+ */
+export function stableQueryHash(value) {
+    return stableStringify(value);
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value) ?? "null";
+    }
+    if (value instanceof AbortSignal) {
+        return '"[signal]"';
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+    }
+    if (value instanceof Set) {
+        return `[${[...value]
+            .map((entry) => stableStringify(entry))
+            .sort()
+            .join(",")}]`;
+    }
+    const record = value;
+    const keys = Object.keys(record)
+        .filter((key) => record[key] !== undefined && !(record[key] instanceof AbortSignal))
+        .sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(",")}}`;
+}

package/runtime/diff.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Diff primitives for incremental `updatePackage` application.
+ *
+ * The runtime uses stable IDs (`sourceId`, `layer.id`) as the diff key
+ * and falls back to a full `map.setStyle` only when structural change
+ * makes incremental patching unsafe (e.g. layer reorder, mapSpec version
+ * mismatch, source type change).
+ *
+ * @module
+ */
+import type { HonuaMapPackage, HonuaMapPackageSourceBinding } from "./map-package.js";
+export interface MapPackageDiff {
+    /** Bindings present in `next` but not `previous`. */
+    addedSourceBindings: HonuaMapPackageSourceBinding[];
+    /** sourceIds present in `previous` but not `next`. */
+    removedSourceIds: string[];
+    /** sourceIds whose locator / filter changed — requires add-then-remove. */
+    changedSourceIds: string[];
+    /** Layer ids newly added in `next`. */
+    addedLayerIds: string[];
+    /** Layer ids removed in `next`. */
+    removedLayerIds: string[];
+    /** Layer ids whose raw layer spec changed. */
+    changedLayerIds: string[];
+    /** Whether the diff is safe to apply incrementally. */
+    incremental: boolean;
+    /** Human-readable reason when `incremental` is false. */
+    structuralReason?: string;
+}
+export declare function diffPackages(previous: HonuaMapPackage, next: HonuaMapPackage): MapPackageDiff;
+//# sourceMappingURL=diff.d.ts.map

package/runtime/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../../src/runtime/diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAC;AAEtF,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,mBAAmB,EAAE,4BAA4B,EAAE,CAAC;IACpD,sDAAsD;IACtD,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,2EAA2E;IAC3E,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,uCAAuC;IACvC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,mCAAmC;IACnC,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,8CAA8C;IAC9C,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,uDAAuD;IACvD,WAAW,EAAE,OAAO,CAAC;IACrB,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,eAAe,GAAG,cAAc,CA6C7F"}