@honua/react 0.0.20-alpha.0 → 0.1.1-beta.0

package/map/automatic-mount-integration.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Incremental integration surface for an automatic Source → MapLibre mount.
+ *
+ * REQ-004 of #390: wire the filter registry, interactions/hit-test, edits, and
+ * realtime feature state into the automatic mount **without a full reload**
+ * where MapLibre supports incremental change (`setFilter`, `setFeatureState`,
+ * source `setData` through {@link MountedAutomaticMapLibreSource.refresh}).
+ *
+ * This module is peer-injected and safe to import in Node/SSR/worker code: it
+ * never imports `maplibre-gl`. Every renderer touch point is duck-typed so any
+ * object exposing the small surface below — including a real MapLibre `Map` —
+ * satisfies it.
+ */
+import type { FeatureId } from "../contract/types.js";
+import { HonuaSdkError } from "../core/error-envelope.js";
+import { type FilterRegistry, type FilterRegistryProjectionOptions, type FilterRegistryUnsubscribe, type RuntimeStyleFilterExpression } from "../filter-registry/index.js";
+import type { HonuaHitTestMap, HonuaHitTestResult, HonuaNormalizeHitTestOptions, HonuaPointerInput } from "../interactions/hit-test.js";
+import type { ExecuteQueryPlanOptions } from "../query-planner/types.js";
+import type { AutomaticMapLibrePlan, MountedAutomaticMapLibreSource } from "./automatic-source-strategy.js";
+/** A stable, machine-readable integration failure. */
+export type AutomaticMapLibreIntegrationErrorCode = "disposed" | "invalid-target";
+export declare class HonuaAutomaticMapLibreIntegrationError extends HonuaSdkError {
+    readonly code: AutomaticMapLibreIntegrationErrorCode;
+    readonly detail?: Readonly<Record<string, unknown>> | undefined;
+    constructor(code: AutomaticMapLibreIntegrationErrorCode, message: string, detail?: Readonly<Record<string, unknown>> | undefined);
+}
+/**
+ * Minimal MapLibre-shaped surface the integration mutates incrementally. A real
+ * `maplibregl.Map` satisfies this; feature-state, filters, and hit-test are all
+ * optional so a raster-only mount still attaches cleanly (it simply has no
+ * interactive layers to bind).
+ */
+export interface AutomaticMapLibreIntegrationMap extends HonuaHitTestMap {
+    /** Replace a layer filter in place (incremental; no style reload). */
+    setFilter?(layerId: string, filter?: unknown): void;
+    /** Read the current layer filter so baked-in geometry filters are preserved. */
+    getFilter?(layerId: string): unknown;
+    setFeatureState?(target: {
+        source: string;
+        id: FeatureId;
+        sourceLayer?: string;
+    }, state: Record<string, unknown>): void;
+    getFeatureState?(target: {
+        source: string;
+        id: FeatureId;
+        sourceLayer?: string;
+    }): Record<string, unknown>;
+    removeFeatureState?(target: {
+        source: string;
+        id: FeatureId;
+        sourceLayer?: string;
+    }, key?: string): void;
+    on?(event: string, layer: string, handler: (...args: unknown[]) => void): void;
+    off?(event: string, layer: string, handler: (...args: unknown[]) => void): void;
+}
+export type AutomaticMapLibreIntegrationDiagnosticCode = "filter-applied" | "filter-registry-bound" | "selection-changed" | "hover-changed" | "realtime-feature-state" | "edit-refreshed" | "capability-unavailable";
+export interface AutomaticMapLibreIntegrationDiagnostic {
+    readonly code: AutomaticMapLibreIntegrationDiagnosticCode;
+    readonly severity: "info" | "warning";
+    readonly message: string;
+    readonly detail?: Readonly<Record<string, unknown>>;
+}
+/** A single realtime feature-state delta targeting a mounted feature. */
+export interface RealtimeFeatureStateDelta {
+    readonly id: FeatureId;
+    readonly state: Record<string, unknown>;
+    readonly sourceLayer?: string;
+}
+export interface AutomaticMapLibreIntegrationOptions {
+    /** Feature-state key toggled on click. @default "selected" */
+    readonly selectionStateKey?: string;
+    /** Feature-state key toggled on hover. @default "hover" */
+    readonly hoverStateKey?: string;
+    /** Enable single-click selection wiring. @default true */
+    readonly selection?: boolean;
+    /** Enable pointer hover wiring. @default true */
+    readonly hover?: boolean;
+    /** Allow multiple simultaneously selected features. @default false */
+    readonly multiSelect?: boolean;
+    /** Vector-tile source layer for feature-state targets. */
+    readonly sourceLayer?: string;
+    /** Observe selection changes. */
+    readonly onSelectionChange?: (selectedIds: ReadonlySet<FeatureId>) => void;
+}
+export interface BindFilterRegistryOptions extends FilterRegistryProjectionOptions {
+    /** Apply the current registry snapshot immediately. @default true */
+    readonly fireImmediately?: boolean;
+}
+/** Cohesive incremental-integration controller for one automatic mount. */
+export interface AutomaticMapLibreIntegration {
+    readonly sourceId: string;
+    readonly layerIds: readonly string[];
+    readonly selectedIds: ReadonlySet<FeatureId>;
+    readonly hoveredId: FeatureId | undefined;
+    readonly appliedFilter: RuntimeStyleFilterExpression | undefined;
+    readonly diagnostics: readonly AutomaticMapLibreIntegrationDiagnostic[];
+    /** Apply a compiled runtime style filter across all mounted layers in place. */
+    setRuntimeFilter(filter: RuntimeStyleFilterExpression | undefined): void;
+    /** Subscribe to a filter registry and project active clauses to the layers. */
+    bindFilterRegistry(registry: FilterRegistry, options?: BindFilterRegistryOptions): FilterRegistryUnsubscribe;
+    /** Apply realtime feature-state deltas incrementally (no reload). */
+    applyRealtimeFeatureState(deltas: readonly RealtimeFeatureStateDelta[]): void;
+    /** Remove a realtime feature-state key (or all state) from a feature. */
+    clearRealtimeFeatureState(id: FeatureId, key?: string): void;
+    /** Programmatically select a feature. */
+    select(id: FeatureId): void;
+    /** Programmatically deselect a feature. */
+    deselect(id: FeatureId): void;
+    /** Clear all selected features. */
+    clearSelection(): void;
+    /** Renderer-neutral hit-test scoped to the mounted layers. */
+    hitTest(input: HonuaPointerInput, options?: HonuaNormalizeHitTestOptions): Promise<HonuaHitTestResult>;
+    /** Refresh mounted data in place (materialized edits flow through setData). */
+    refresh(options?: ExecuteQueryPlanOptions): Promise<AutomaticMapLibrePlan>;
+    /** Remove every listener/subscription and clear feature state. Leak-free. */
+    dispose(): void;
+}
+/**
+ * Attach an incremental-integration controller to a mounted automatic source.
+ *
+ * @example
+ * ```ts
+ * const plan = explainAutomaticSourceToMapLibre(source, { queryPlan });
+ * const mounted = await mountAutomaticSourceToMapLibre(map, source, plan, { queryPlan });
+ * const integration = attachAutomaticMapLibreInteractions(map, mounted, {
+ *   onSelectionChange: (ids) => sidebar.render([...ids]),
+ * });
+ * integration.bindFilterRegistry(registry, { sourceId: source.descriptor.id });
+ * // realtime delta, no reload:
+ * integration.applyRealtimeFeatureState([{ id: 42, state: { status: "active" } }]);
+ * ```
+ */
+export declare function attachAutomaticMapLibreInteractions(map: AutomaticMapLibreIntegrationMap, mounted: MountedAutomaticMapLibreSource, options?: AutomaticMapLibreIntegrationOptions): AutomaticMapLibreIntegration;
+//# sourceMappingURL=automatic-mount-integration.d.ts.map

package/map/automatic-mount-integration.d.ts.map

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

package/map/automatic-mount-integration.js

@@ -0,0 +1,305 @@
+/**
+ * Incremental integration surface for an automatic Source → MapLibre mount.
+ *
+ * REQ-004 of #390: wire the filter registry, interactions/hit-test, edits, and
+ * realtime feature state into the automatic mount **without a full reload**
+ * where MapLibre supports incremental change (`setFilter`, `setFeatureState`,
+ * source `setData` through {@link MountedAutomaticMapLibreSource.refresh}).
+ *
+ * This module is peer-injected and safe to import in Node/SSR/worker code: it
+ * never imports `maplibre-gl`. Every renderer touch point is duck-typed so any
+ * object exposing the small surface below — including a real MapLibre `Map` —
+ * satisfies it.
+ */
+import { HonuaSdkError } from "../core/error-envelope.js";
+import { compileRuntimeStyleFilter, selectActiveFilterClauses, } from "../filter-registry/index.js";
+import { hitTestMap } from "../interactions/hit-test.js";
+export class HonuaAutomaticMapLibreIntegrationError extends HonuaSdkError {
+    code;
+    detail;
+    constructor(code, message, detail) {
+        super(AUTOMATIC_MAPLIBRE_INTEGRATION_ERROR_CODES[code], message, { context: detail });
+        this.code = code;
+        this.detail = detail;
+        this.name = "HonuaAutomaticMapLibreIntegrationError";
+    }
+}
+const AUTOMATIC_MAPLIBRE_INTEGRATION_ERROR_CODES = {
+    disposed: "map.automatic-integration.disposed",
+    "invalid-target": "map.automatic-integration.invalid-target",
+};
+/**
+ * Attach an incremental-integration controller to a mounted automatic source.
+ *
+ * @example
+ * ```ts
+ * const plan = explainAutomaticSourceToMapLibre(source, { queryPlan });
+ * const mounted = await mountAutomaticSourceToMapLibre(map, source, plan, { queryPlan });
+ * const integration = attachAutomaticMapLibreInteractions(map, mounted, {
+ *   onSelectionChange: (ids) => sidebar.render([...ids]),
+ * });
+ * integration.bindFilterRegistry(registry, { sourceId: source.descriptor.id });
+ * // realtime delta, no reload:
+ * integration.applyRealtimeFeatureState([{ id: 42, state: { status: "active" } }]);
+ * ```
+ */
+export function attachAutomaticMapLibreInteractions(map, mounted, options = {}) {
+    const { selectionStateKey = "selected", hoverStateKey = "hover", selection = true, hover = true, multiSelect = false, sourceLayer, onSelectionChange, } = options;
+    const sourceId = mounted.sourceId;
+    const layerIds = [...mounted.layerIds];
+    const diagnostics = [];
+    const selected = new Set();
+    let hoveredId;
+    let appliedFilter;
+    let disposed = false;
+    let registryUnsubscribe;
+    // Capture each layer's baked-in filter (e.g. the geojson geometry-type
+    // matrix) so runtime filters compose instead of clobbering them.
+    const baseFilters = new Map();
+    if (typeof map.getFilter === "function") {
+        for (const layerId of layerIds) {
+            try {
+                baseFilters.set(layerId, map.getFilter(layerId));
+            }
+            catch {
+                /* layer without a readable filter */
+            }
+        }
+    }
+    const featureStateCapable = typeof map.setFeatureState === "function" && typeof map.removeFeatureState === "function";
+    const filterCapable = typeof map.setFilter === "function";
+    const eventCapable = typeof map.on === "function" && typeof map.off === "function";
+    const assertLive = () => {
+        if (disposed)
+            throw new HonuaAutomaticMapLibreIntegrationError("disposed", "The automatic MapLibre integration was disposed.");
+    };
+    const setFeatureStateSafe = (id, state, layer) => {
+        map.setFeatureState?.(featureTarget(sourceId, id, layer ?? sourceLayer), state);
+    };
+    const removeFeatureStateSafe = (id, key) => {
+        map.removeFeatureState?.(featureTarget(sourceId, id, sourceLayer), key);
+    };
+    const applyFilterToLayers = (filter) => {
+        appliedFilter = filter;
+        if (!filterCapable) {
+            diagnostics.push({
+                code: "capability-unavailable",
+                severity: "warning",
+                message: "The renderer does not expose setFilter; runtime filter was recorded but not applied.",
+            });
+            return;
+        }
+        for (const layerId of layerIds) {
+            const base = baseFilters.get(layerId);
+            const composed = composeFilter(base, filter);
+            map.setFilter?.(layerId, composed);
+        }
+        diagnostics.push({
+            code: "filter-applied",
+            severity: "info",
+            message: filter ? "Applied a runtime style filter across mounted layers." : "Cleared the runtime style filter.",
+            detail: { layerCount: layerIds.length },
+        });
+    };
+    const notifySelection = () => onSelectionChange?.(selected);
+    const selectInternal = (id) => {
+        if (!featureStateCapable)
+            return;
+        if (!multiSelect)
+            clearSelectionInternal();
+        map.setFeatureState?.(featureTarget(sourceId, id, sourceLayer), { [selectionStateKey]: true });
+        selected.add(id);
+    };
+    const deselectInternal = (id) => {
+        if (!selected.has(id))
+            return;
+        map.setFeatureState?.(featureTarget(sourceId, id, sourceLayer), { [selectionStateKey]: false });
+        selected.delete(id);
+    };
+    const clearSelectionInternal = () => {
+        for (const id of selected)
+            map.setFeatureState?.(featureTarget(sourceId, id, sourceLayer), { [selectionStateKey]: false });
+        selected.clear();
+    };
+    const onLayerClick = (...args) => {
+        const id = firstFeatureId(args[0]);
+        if (id === undefined)
+            return;
+        if (selected.has(id))
+            deselectInternal(id);
+        else
+            selectInternal(id);
+        diagnostics.push({ code: "selection-changed", severity: "info", message: "Selection toggled from a click." });
+        notifySelection();
+    };
+    const onLayerMove = (...args) => {
+        const id = firstFeatureId(args[0]);
+        if (id === undefined)
+            return;
+        if (hoveredId !== undefined && hoveredId !== id)
+            map.setFeatureState?.(featureTarget(sourceId, hoveredId, sourceLayer), { [hoverStateKey]: false });
+        hoveredId = id;
+        map.setFeatureState?.(featureTarget(sourceId, id, sourceLayer), { [hoverStateKey]: true });
+    };
+    const onLayerLeave = () => {
+        if (hoveredId === undefined)
+            return;
+        map.setFeatureState?.(featureTarget(sourceId, hoveredId, sourceLayer), { [hoverStateKey]: false });
+        hoveredId = undefined;
+    };
+    // Wire pointer interactions per layer (the geojson auto mount installs one
+    // layer per geometry kind, so a single source can carry several layers).
+    const wiredClick = selection && featureStateCapable && eventCapable;
+    const wiredHover = hover && featureStateCapable && eventCapable;
+    if (wiredClick)
+        for (const layerId of layerIds)
+            map.on?.("click", layerId, onLayerClick);
+    if (wiredHover)
+        for (const layerId of layerIds) {
+            map.on?.("mousemove", layerId, onLayerMove);
+            map.on?.("mouseleave", layerId, onLayerLeave);
+        }
+    if ((selection || hover) && !featureStateCapable) {
+        diagnostics.push({
+            code: "capability-unavailable",
+            severity: "warning",
+            message: "The renderer does not expose feature-state; selection and hover wiring were skipped.",
+        });
+    }
+    return {
+        sourceId,
+        layerIds,
+        get selectedIds() {
+            return selected;
+        },
+        get hoveredId() {
+            return hoveredId;
+        },
+        get appliedFilter() {
+            return appliedFilter;
+        },
+        get diagnostics() {
+            return diagnostics;
+        },
+        setRuntimeFilter(filter) {
+            assertLive();
+            applyFilterToLayers(filter);
+        },
+        bindFilterRegistry(registry, bindOptions = {}) {
+            assertLive();
+            const project = (clauses) => applyFilterToLayers(compileRuntimeStyleFilter(clauses));
+            registryUnsubscribe?.();
+            const unsubscribe = registry.subscribe((event) => {
+                project(selectActiveFilterClauses(event.snapshot, bindOptions));
+            });
+            registryUnsubscribe = unsubscribe;
+            if (bindOptions.fireImmediately !== false)
+                project(selectActiveFilterClauses(registry.snapshot, bindOptions));
+            diagnostics.push({
+                code: "filter-registry-bound",
+                severity: "info",
+                message: "Bound the filter registry to the mounted layers.",
+            });
+            return () => {
+                unsubscribe();
+                if (registryUnsubscribe === unsubscribe)
+                    registryUnsubscribe = undefined;
+            };
+        },
+        applyRealtimeFeatureState(deltas) {
+            assertLive();
+            if (!featureStateCapable) {
+                diagnostics.push({
+                    code: "capability-unavailable",
+                    severity: "warning",
+                    message: "The renderer does not expose setFeatureState; realtime deltas were dropped.",
+                });
+                return;
+            }
+            for (const delta of deltas) {
+                if (delta.id === undefined || delta.id === null)
+                    throw new HonuaAutomaticMapLibreIntegrationError("invalid-target", "Realtime deltas require a feature id.");
+                setFeatureStateSafe(delta.id, delta.state, delta.sourceLayer);
+            }
+            diagnostics.push({
+                code: "realtime-feature-state",
+                severity: "info",
+                message: "Applied realtime feature-state deltas in place.",
+                detail: { count: deltas.length },
+            });
+        },
+        clearRealtimeFeatureState(id, key) {
+            assertLive();
+            removeFeatureStateSafe(id, key);
+        },
+        select(id) {
+            assertLive();
+            selectInternal(id);
+            diagnostics.push({ code: "selection-changed", severity: "info", message: "Feature selected programmatically." });
+            notifySelection();
+        },
+        deselect(id) {
+            assertLive();
+            deselectInternal(id);
+            diagnostics.push({
+                code: "selection-changed",
+                severity: "info",
+                message: "Feature deselected programmatically.",
+            });
+            notifySelection();
+        },
+        clearSelection() {
+            assertLive();
+            clearSelectionInternal();
+            diagnostics.push({ code: "selection-changed", severity: "info", message: "Selection cleared programmatically." });
+            notifySelection();
+        },
+        hitTest(input, hitOptions = {}) {
+            assertLive();
+            return hitTestMap(map, input, { layers: layerIds, ...hitOptions });
+        },
+        async refresh(refreshOptions) {
+            assertLive();
+            const plan = await mounted.refresh(refreshOptions);
+            diagnostics.push({ code: "edit-refreshed", severity: "info", message: "Refreshed mounted data in place." });
+            return plan;
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            registryUnsubscribe?.();
+            registryUnsubscribe = undefined;
+            if (wiredClick)
+                for (const layerId of layerIds)
+                    map.off?.("click", layerId, onLayerClick);
+            if (wiredHover)
+                for (const layerId of layerIds) {
+                    map.off?.("mousemove", layerId, onLayerMove);
+                    map.off?.("mouseleave", layerId, onLayerLeave);
+                }
+            if (featureStateCapable) {
+                onLayerLeave();
+                clearSelectionInternal();
+            }
+        },
+    };
+}
+function composeFilter(base, runtime) {
+    const hasBase = Array.isArray(base) && base.length > 0;
+    if (runtime === undefined)
+        return hasBase ? base : undefined;
+    if (!hasBase)
+        return runtime;
+    return ["all", base, runtime];
+}
+function featureTarget(source, id, sourceLayer) {
+    return sourceLayer ? { source, id, sourceLayer } : { source, id };
+}
+function firstFeatureId(event) {
+    if (!event || typeof event !== "object")
+        return undefined;
+    const features = event.features;
+    const id = features?.[0]?.id;
+    return id === undefined || id === null ? undefined : id;
+}

package/map/automatic-source-strategy.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Explainable, dependency-free automatic Source -> MapLibre strategy selection.
+ *
+ * Planning is pure and renderer-neutral. Mounting consumes only the minimal
+ * injected MapLibre host surface and delegates to the focused feature/raster
+ * adapters where possible.
+ */
+import type { Source } from "../contract/types.js";
+import { type HonuaErrorOptions, HonuaSdkError } from "../core/error-envelope.js";
+import type { ExecuteQueryPlanOptions, QueryExecutionPlanV1 } from "../query-planner/types.js";
+import { type MapLibreRasterStrategy } from "./raster-source-strategy.js";
+import { type MapLibreGeometryKind, type MapLibreSourceWorkflowState, type SourceToMapLibreMap } from "./source-to-maplibre.js";
+export declare const AUTOMATIC_MAPLIBRE_PLAN_KIND: "honua.maplibre-source-plan";
+export declare const AUTOMATIC_MAPLIBRE_PLAN_VERSION: "1.0";
+export declare const MAX_AUTOMATIC_GEOJSON_FEATURES = 100000;
+export type AutomaticMapLibreStrategy = "geojson-query" | "vector-tiles" | "pmtiles-vector" | "pmtiles-raster" | "dynamic-query-tiles" | MapLibreRasterStrategy;
+export type AutomaticMapLibreReasonCode = "selected" | "eligible-not-selected" | "protocol-mismatch" | "capability-mismatch" | "missing-query-plan" | "unsupported-query-plan" | "plan-context-mismatch" | "unbounded-materialization" | "missing-metadata" | "invalid-option" | "unsafe-url" | "unsupported-crs" | "stale-evidence" | "override-mismatch";
+export interface AutomaticMapLibreCandidate {
+    readonly strategy: AutomaticMapLibreStrategy;
+    readonly eligible: boolean;
+    readonly reason: AutomaticMapLibreReasonCode;
+    readonly fidelity: "exact" | "unsupported";
+    readonly dataPath: "native" | "materialized";
+    readonly requiredPeers: readonly ("maplibre-gl" | "pmtiles")[];
+    readonly message: string;
+}
+export interface AutomaticMapLibreDiagnostic {
+    readonly code: AutomaticMapLibreReasonCode;
+    readonly severity: "info" | "warning" | "error";
+    readonly strategy?: AutomaticMapLibreStrategy;
+    readonly message: string;
+}
+export interface AutomaticMapLibreNativeSourceSpec {
+    readonly type: "vector" | "raster";
+    readonly tiles?: readonly string[];
+    readonly url?: string;
+    readonly scheme?: "xyz" | "tms";
+    readonly tileSize?: number;
+    readonly minzoom?: number;
+    readonly maxzoom?: number;
+    readonly bounds?: readonly [number, number, number, number];
+    readonly attribution?: string;
+    readonly promoteId?: string | Readonly<Record<string, string>>;
+    readonly volatile?: boolean;
+}
+export interface ExplainAutomaticMapLibreOptions {
+    /** Accepted, immutable query plan. Required for materialized GeoJSON. */
+    readonly queryPlan?: QueryExecutionPlanV1;
+    /** A source spec built by the dynamic-query-tile helpers. */
+    readonly queryTileSource?: AutomaticMapLibreNativeSourceSpec;
+    /** Required layer name for vector tile and vector PMTiles sources. */
+    readonly sourceLayer?: string;
+    /** Archive payload evidence obtained from PMTiles metadata. */
+    readonly pmtilesType?: "vector" | "raster";
+    readonly override?: AutomaticMapLibreStrategy;
+    readonly sourceId?: string;
+    readonly layerId?: string;
+    readonly beforeId?: string;
+    readonly geometry?: MapLibreGeometryKind | "auto";
+    readonly paint?: Readonly<Record<string, unknown>>;
+    readonly layout?: Readonly<Record<string, unknown>>;
+    readonly minzoom?: number;
+    readonly maxzoom?: number;
+    readonly tileSize?: number;
+    readonly format?: string;
+    readonly transparent?: boolean;
+    /** Caller-observed metadata time and explicit freshness budget. */
+    readonly evidence?: {
+        readonly observedAt: string;
+        readonly maxAgeMs: number;
+        /** Explicit clock evidence keeps planning deterministic. */
+        readonly now: string;
+    };
+}
+export interface AutomaticMapLibrePlan {
+    readonly kind: typeof AUTOMATIC_MAPLIBRE_PLAN_KIND;
+    readonly version: typeof AUTOMATIC_MAPLIBRE_PLAN_VERSION;
+    readonly id: string;
+    readonly sourceId: string;
+    readonly protocol: string;
+    readonly selected?: AutomaticMapLibreCandidate;
+    readonly candidates: readonly AutomaticMapLibreCandidate[];
+    readonly diagnostics: readonly AutomaticMapLibreDiagnostic[];
+    readonly bounds?: readonly [number, number, number, number];
+    readonly freshness: Readonly<{
+        mode: string;
+        observedAt?: string;
+        maxAgeMs?: number;
+        stale: boolean;
+    }>;
+    readonly provenance: Readonly<{
+        endpoint: string;
+        sourceVersion?: string;
+        schemaVersion?: string;
+        authorizationScope: readonly string[];
+        queryPlanId?: string;
+        queryPlanFingerprint?: string;
+    }>;
+    readonly cache: "source-owned" | "immutable-archive" | "query-plan-bypass";
+    readonly source?: AutomaticMapLibreNativeSourceSpec;
+    readonly layers: readonly Readonly<Record<string, unknown>>[];
+}
+export type AutomaticMapLibreWorkflowState = MapLibreSourceWorkflowState | "cancelled";
+export interface MountedAutomaticMapLibreSource {
+    readonly strategy: AutomaticMapLibreStrategy;
+    readonly sourceId: string;
+    readonly layerIds: readonly string[];
+    readonly state: AutomaticMapLibreWorkflowState;
+    readonly diagnostics: readonly AutomaticMapLibreDiagnostic[];
+    readonly ready: Promise<AutomaticMapLibrePlan>;
+    refresh(options?: ExecuteQueryPlanOptions): Promise<AutomaticMapLibrePlan>;
+    cancel(reason?: unknown): void;
+    dispose(): void;
+}
+export type AutomaticMapLibreErrorCode = "no-eligible-strategy" | "stale-plan" | "source-conflict" | "layer-conflict" | "map-mutation-failed" | "cancelled" | "disposed";
+export declare class HonuaAutomaticMapLibreStrategyError extends HonuaSdkError {
+    readonly code: AutomaticMapLibreErrorCode;
+    readonly detail?: Readonly<Record<string, unknown>> | undefined;
+    constructor(code: AutomaticMapLibreErrorCode, message: string, detail?: Readonly<Record<string, unknown>> | undefined, options?: HonuaErrorOptions);
+}
+/** Explain every strategy and select the first exact eligible candidate. */
+export declare function explainAutomaticSourceToMapLibre<T>(source: Source<T>, options?: ExplainAutomaticMapLibreOptions): AutomaticMapLibrePlan;
+/** Mount an explained plan through one cross-strategy lifecycle. */
+export declare function mountAutomaticSourceToMapLibre<T>(map: SourceToMapLibreMap, source: Source<T>, plan: AutomaticMapLibrePlan, options?: ExplainAutomaticMapLibreOptions & ExecuteQueryPlanOptions): Promise<MountedAutomaticMapLibreSource>;
+//# sourceMappingURL=automatic-source-strategy.d.ts.map

package/map/automatic-source-strategy.d.ts.map

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