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

package/react/use-mounted-source.js

@@ -0,0 +1,346 @@
+/**
+ * {@link useMountedSource} — the React lifecycle wrapper around the
+ * data-to-map bridge's `mountSource` (REQ-002 of the react depth pass).
+ *
+ * One bridge mount per effect run: the mount effect creates a fresh
+ * `MountedSource` and its cleanup aborts any in-flight mount and disposes the
+ * handle (idempotent), so React 18/19 StrictMode's mount → unmount → mount
+ * never leaks MapLibre sources, layers, or listeners and never double-adds.
+ *
+ * Prop changes are diffed instead of torn down:
+ * - `query` → `handle.setFilter(query)` (GeoJSON `setData` / tile URL rewrite);
+ * - `renderer` (a first-class renderer object from `@honua/sdk-js/style`) →
+ *   `handle.setRenderer(renderer)`, which diffs paint/layout in place and
+ *   recreates only the owned layers on a structural renderer change;
+ * - `paint` / `layout` → per-property `map.setPaintProperty` /
+ *   `map.setLayoutProperty` on the bridge-owned layers (falling back to a full
+ *   remount when the host map does not expose those methods);
+ * - structural options (strategy, ids, custom `layers`, geometry, tiles…) →
+ *   remount.
+ *
+ * SSR-safe: no `window` / `document` access at module scope.
+ *
+ * @module
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { mountSource } from "../map/data-to-map-bridge.js";
+import { defaultPaint, defaultPolygonOutlinePaint } from "../map/geojson-projection.js";
+import { useHonuaMap } from "./external-map.js";
+import { stableQueryHash } from "./query-cache.js";
+const IDLE_STATE = Object.freeze({
+    handle: null,
+    diagnostics: null,
+    error: undefined,
+    isMounting: false,
+});
+function isAbortError(error) {
+    return ((error instanceof DOMException && error.name === "AbortError") ||
+        (error instanceof Error && error.name === "AbortError"));
+}
+/**
+ * Everything that requires a structural remount when it changes. `query`,
+ * `renderer`, `paint`, and `layout` are intentionally absent (diff-updated in
+ * place through `setFilter` / `setRenderer` / property setters);
+ * function-valued options (`popup.factory` / `popup.render`, callbacks) are
+ * read through a ref so their identity never forces a remount.
+ */
+function structuralSignature(options) {
+    return stableQueryHash({
+        strategy: options.strategy,
+        sourceId: options.sourceId,
+        layerId: options.layerId,
+        beforeId: options.beforeId,
+        geometry: options.geometry,
+        layers: options.layers,
+        maxGeoJsonFeatures: options.maxGeoJsonFeatures,
+        queryTiles: options.queryTiles,
+        sourceLayer: options.sourceLayer,
+        attribution: options.attribution,
+        fitBounds: options.fitBounds,
+        hover: options.hover,
+        popup: options.popup
+            ? {
+                fields: options.popup.fields,
+                title: options.popup.title,
+                // Adding/removing a custom renderer rewires the bridge's popup
+                // binding (structural); identity changes of an existing renderer or
+                // factory are delivered through the stable wrappers below instead.
+                hasRender: options.popup.render !== undefined,
+            }
+            : undefined,
+    });
+}
+/**
+ * Stable identity for a renderer-object option: its serializable descriptor.
+ * Renderer instances are commonly rebuilt inline every render, so identity
+ * must come from `toJSON()`, not object reference.
+ */
+function rendererSignature(renderer) {
+    if (renderer === undefined)
+        return "none";
+    try {
+        return stableQueryHash(renderer.toJSON());
+    }
+    catch {
+        // Malformed renderer objects fail mountSource validation with a typed
+        // error; the signature only needs to be deterministic.
+        return stableQueryHash({ kind: renderer.kind });
+    }
+}
+/**
+ * Wrap a popup option so its function-valued members (`factory`, `render`)
+ * are resolved from the latest props at call time. The bridge captures the
+ * popup object once at mount; without this, a renderer or factory that closes
+ * over React state would keep using its mount-time closure.
+ */
+function livePopupOptions(snapshot, optionsRef) {
+    return {
+        ...snapshot,
+        factory: () => (optionsRef.current.popup ?? snapshot).factory(),
+        ...(snapshot.render !== undefined
+            ? {
+                render: (context) => (optionsRef.current.popup?.render ?? snapshot.render)?.(context),
+            }
+            : {}),
+    };
+}
+const KIND_BY_SUFFIX = [
+    ["-polygon-outline", "polygonOutline"],
+    ["-polygon", "polygon"],
+    ["-line", "line"],
+    ["-point", "point"],
+];
+function kindForLayerId(layerId) {
+    for (const [suffix, kind] of KIND_BY_SUFFIX) {
+        if (layerId.endsWith(suffix))
+            return kind;
+    }
+    return undefined;
+}
+function defaultPaintFor(kind) {
+    return kind === "polygonOutline" ? defaultPolygonOutlinePaint() : defaultPaint(kind);
+}
+/**
+ * Apply a `paint` / `layout` change to the bridge's default layer matrix in
+ * place. Returns `false` when the host map lacks the property setters (the
+ * caller then falls back to a structural remount). Keys removed from an
+ * override are restored to the bridge default (paint) or reset (`undefined`,
+ * layout), keyed off the previously applied override.
+ */
+function applyRendererDiff(map, handle, previous, next) {
+    const host = map;
+    if (typeof host.setPaintProperty !== "function" || typeof host.setLayoutProperty !== "function") {
+        return false;
+    }
+    for (const layerId of handle.layerIds) {
+        const kind = kindForLayerId(layerId);
+        if (kind === undefined)
+            return false; // custom layer set: structural
+        const defaults = defaultPaintFor(kind);
+        const prevPaint = previous?.paint?.[kind] ?? {};
+        const nextPaint = next.paint?.[kind] ?? {};
+        for (const key of new Set([...Object.keys(prevPaint), ...Object.keys(nextPaint)])) {
+            host.setPaintProperty(layerId, key, key in nextPaint ? nextPaint[key] : defaults[key]);
+        }
+        const prevLayout = previous?.layout?.[kind] ?? {};
+        const nextLayout = next.layout?.[kind] ?? {};
+        for (const key of new Set([...Object.keys(prevLayout), ...Object.keys(nextLayout)])) {
+            host.setLayoutProperty(layerId, key, key in nextLayout ? nextLayout[key] : undefined);
+        }
+    }
+    return true;
+}
+/**
+ * Mount a contract `Source` on a MapLibre map through the data-to-map bridge
+ * for the lifetime of the component.
+ *
+ * Pass the map explicitly, or pass `undefined` to resolve it from the nearest
+ * {@link HonuaMapProvider} / `HonuaMap` (external `@vis.gl/react-maplibre`
+ * interop works the same way — hand over `mapRef.getMap()`).
+ *
+ * @example
+ * ```tsx
+ * const { diagnostics, error } = useMountedSource(map, source, {
+ *   query: { where: "STATUS = 'OPEN'" },
+ *   hover: true,
+ *   onDiagnostics: (d) => console.log(d.strategy, d.featureCount),
+ * });
+ * ```
+ *
+ * @experimental
+ */
+export function useMountedSource(map, source, options = {}) {
+    const resolvedMap = useHonuaMap(map);
+    const enabled = options.enabled ?? true;
+    // Latest options snapshot for effects: mount reads it once per run; the
+    // diff effects read it when their hash keys change. Callback / factory
+    // identity changes therefore never remount or re-run anything.
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    const structuralKey = structuralSignature(options);
+    const queryKey = stableQueryHash(options.query ?? null);
+    const rendererKey = stableQueryHash({ paint: options.paint, layout: options.layout });
+    const rendererObjectKey = rendererSignature(options.renderer);
+    const [remountToken, setRemountToken] = useState(0);
+    const [state, setState] = useState(IDLE_STATE);
+    // Hash keys applied by the *current* mount; diff effects compare against
+    // these so a fresh mount (which reads the latest options) is never followed
+    // by a redundant setFilter / repaint.
+    const appliedRef = useRef(null);
+    // ── Mount / structural remount ─────────────────────────────────
+    // biome-ignore lint/correctness/useExhaustiveDependencies: `structuralKey` hashes every structural option; the rest is read via optionsRef.
+    useEffect(() => {
+        if (!resolvedMap || !source || !enabled) {
+            appliedRef.current = null;
+            setState(IDLE_STATE);
+            return;
+        }
+        let cancelled = false;
+        let mounted = null;
+        const controller = new AbortController();
+        const snapshot = optionsRef.current;
+        const { enabled: _enabled, onDiagnostics: _onDiagnostics, onError: _onError, ...mountOptions } = snapshot;
+        appliedRef.current = null;
+        setState({ handle: null, diagnostics: null, error: undefined, isMounting: true });
+        // Popup callbacks are wrapped so the bridge (which captures the popup
+        // object once) always calls the latest `factory` / `render` props.
+        const popup = mountOptions.popup ? livePopupOptions(mountOptions.popup, optionsRef) : undefined;
+        mountSource(resolvedMap, source, {
+            ...mountOptions,
+            ...(popup ? { popup } : {}),
+            signal: controller.signal,
+        }).then((handle) => {
+            if (cancelled) {
+                // StrictMode / fast unmount: the mount resolved after cleanup ran.
+                // Dispose immediately — dispose() is idempotent, so a second call
+                // from a racing cleanup is safe.
+                handle.dispose();
+                return;
+            }
+            mounted = handle;
+            appliedRef.current = {
+                query: stableQueryHash(snapshot.query ?? null),
+                renderer: stableQueryHash({ paint: snapshot.paint, layout: snapshot.layout }),
+                rendererObject: rendererSignature(snapshot.renderer),
+            };
+            const diagnostics = handle.diagnostics;
+            setState({ handle, diagnostics, error: undefined, isMounting: false });
+            optionsRef.current.onDiagnostics?.(diagnostics);
+        }, (error) => {
+            if (cancelled || controller.signal.aborted || isAbortError(error))
+                return;
+            setState({ handle: null, diagnostics: null, error, isMounting: false });
+            optionsRef.current.onError?.(error);
+        });
+        return () => {
+            cancelled = true;
+            // Abort first so an in-flight mount never touches the map, then dispose
+            // whatever this run mounted. Both are idempotent, so the StrictMode
+            // mount → cleanup → mount sequence releases every MapLibre resource.
+            controller.abort(new DOMException("useMountedSource unmounted", "AbortError"));
+            try {
+                mounted?.dispose();
+            }
+            catch (error) {
+                optionsRef.current.onError?.(error);
+            }
+        };
+    }, [resolvedMap, source, enabled, structuralKey, remountToken]);
+    // ── Query prop → setFilter diff update ─────────────────────────
+    const handle = state.handle;
+    useEffect(() => {
+        if (!handle || handle.state === "disposed")
+            return;
+        const applied = appliedRef.current;
+        if (!applied || applied.query === queryKey)
+            return;
+        applied.query = queryKey;
+        handle.setFilter(optionsRef.current.query).then((diagnostics) => {
+            if (handle.state === "disposed")
+                return;
+            setState((current) => (current.handle === handle ? { ...current, diagnostics, error: undefined } : current));
+            optionsRef.current.onDiagnostics?.(diagnostics);
+        }, (error) => {
+            if (handle.state === "disposed" || isAbortError(error))
+                return;
+            setState((current) => (current.handle === handle ? { ...current, error } : current));
+            optionsRef.current.onError?.(error);
+        });
+    }, [handle, queryKey]);
+    // ── renderer object prop → setRenderer diff update ─────────────
+    useEffect(() => {
+        if (!handle || handle.state === "disposed")
+            return;
+        const applied = appliedRef.current;
+        if (!applied || applied.rendererObject === rendererObjectKey)
+            return;
+        applied.rendererObject = rendererObjectKey;
+        handle.setRenderer(optionsRef.current.renderer).then((diagnostics) => {
+            if (handle.state === "disposed")
+                return;
+            setState((current) => (current.handle === handle ? { ...current, diagnostics, error: undefined } : current));
+            optionsRef.current.onDiagnostics?.(diagnostics);
+        }, (error) => {
+            if (handle.state === "disposed" || isAbortError(error))
+                return;
+            setState((current) => (current.handle === handle ? { ...current, error } : current));
+            optionsRef.current.onError?.(error);
+        });
+    }, [handle, rendererObjectKey]);
+    // ── paint/layout props → in-place repaint (or structural remount) ──
+    const previousRendererRef = useRef(undefined);
+    useEffect(() => {
+        if (!handle || handle.state === "disposed" || !resolvedMap)
+            return;
+        const applied = appliedRef.current;
+        if (!applied)
+            return;
+        if (applied.renderer === rendererKey) {
+            previousRendererRef.current = {
+                paint: optionsRef.current.paint,
+                layout: optionsRef.current.layout,
+            };
+            return;
+        }
+        if (optionsRef.current.renderer !== undefined) {
+            // A first-class renderer object owns the layer styling; the
+            // paint/layout override matrix applies only to geometry-default layers.
+            applied.renderer = rendererKey;
+            previousRendererRef.current = { paint: optionsRef.current.paint, layout: optionsRef.current.layout };
+            return;
+        }
+        const next = { paint: optionsRef.current.paint, layout: optionsRef.current.layout };
+        if (optionsRef.current.layers === undefined &&
+            applyRendererDiff(resolvedMap, handle, previousRendererRef.current, next)) {
+            applied.renderer = rendererKey;
+            previousRendererRef.current = next;
+            return;
+        }
+        // Custom layer sets and hosts without property setters cannot be diffed
+        // in place: fall back to a full, transactional remount.
+        setRemountToken((token) => token + 1);
+    }, [handle, resolvedMap, rendererKey]);
+    const refresh = useCallback(() => {
+        const current = handle;
+        if (!current || current.state === "disposed")
+            return;
+        current.refresh().then((diagnostics) => {
+            if (current.state === "disposed")
+                return;
+            setState((existing) => existing.handle === current ? { ...existing, diagnostics, error: undefined } : existing);
+            optionsRef.current.onDiagnostics?.(diagnostics);
+        }, (error) => {
+            if (current.state === "disposed" || isAbortError(error))
+                return;
+            setState((existing) => (existing.handle === current ? { ...existing, error } : existing));
+            optionsRef.current.onError?.(error);
+        });
+    }, [handle]);
+    return useMemo(() => ({
+        handle: state.handle,
+        diagnostics: state.diagnostics,
+        error: state.error,
+        isMounting: state.isMounting,
+        refresh,
+    }), [state, refresh]);
+}

package/runtime/edit-snapping.d.ts

@@ -0,0 +1,107 @@
+/**
+ * MapLibre runtime binding for edit-sketch snapping.
+ *
+ * Wires pointer-move on a MapLibre-shaped map to the renderer-neutral
+ * snapping engine in `contract/edit-snapping.ts`, applies snapped
+ * coordinates to an `EditSketchWorkflowModel`, surfaces snapped / unsnapped
+ * events, and maintains a default visual indicator via a lightweight GeoJSON
+ * circle layer.
+ *
+ * The map interfaces are duck-typed (same pattern as
+ * `interactions/feature-state.ts`) so the SDK carries no hard runtime
+ * dependency on `maplibre-gl`.
+ *
+ * @module
+ */
+import type { EditSketchTool, EditSketchWorkflowModel } from "../contract/edit-sketch.js";
+import { type SnapCandidate, type SnapIndex, type SnapPosition, type SnapResolution, type SnapScreenPoint, type SnappingConfig } from "../contract/edit-snapping.js";
+/** Minimal subset of a MapLibre `Map` needed for snapping. */
+export interface SnappingMap {
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    off(event: string, handler: (...args: unknown[]) => void): void;
+    project(position: readonly [number, number]): SnapScreenPoint | {
+        x: number;
+        y: number;
+    };
+    addSource?(id: string, source: Record<string, unknown>): void;
+    removeSource?(id: string): void;
+    addLayer?(layer: Record<string, unknown>, beforeId?: string): void;
+    removeLayer?(id: string): void;
+    getSource?(id: string): unknown;
+    getLayer?(id: string): unknown;
+}
+export interface EditSketchSnapIndicatorOptions {
+    /** Render the default indicator layer. @default true */
+    enabled?: boolean;
+    /** Indicator source and layer id. @default "honua-snap-indicator" */
+    id?: string;
+    /** Paint overrides merged over the default circle paint. */
+    paint?: Record<string, unknown>;
+    /** Insert the indicator layer before this layer id. */
+    beforeId?: string;
+}
+export interface EditSketchSnappingEvents {
+    /** Fired when the pointer acquires or changes a snap target. */
+    onSnap?(resolution: SnapResolution): void;
+    /** Fired when the pointer leaves a snap target; receives the lost candidate. */
+    onUnsnap?(previous: SnapCandidate): void;
+}
+export interface BindEditSketchSnappingOptions<T = Record<string, unknown>> extends EditSketchSnappingEvents {
+    /** Snap index over the loaded snap-source features. */
+    index: SnapIndex;
+    /**
+     * Sketch workflow whose snapping config drives resolution and that
+     * receives snapped geometry via {@link EditSketchSnappingHandle.applySketchGeometry}.
+     * When omitted, pass `config` and consume snaps through events / `current`.
+     */
+    model?: EditSketchWorkflowModel<T>;
+    /** Snapping configuration when no model is bound (or overrides for one-off use). */
+    config?: Partial<SnappingConfig>;
+    /** Pointer event name to listen for. @default "mousemove" */
+    pointerEvent?: string;
+    /** Default snap indicator; `false` disables it. */
+    indicator?: boolean | EditSketchSnapIndicatorOptions;
+}
+export interface EditSketchSnappingHandle {
+    /** The currently snapped candidate, if any. */
+    readonly current: SnapCandidate | undefined;
+    /** Resolve a pointer position without going through a map event. */
+    resolve(input: {
+        point: SnapScreenPoint;
+        position: SnapPosition;
+    }): SnapResolution;
+    /** Return the snapped position for `position`, or `position` unchanged. */
+    snapPosition(position: SnapPosition): SnapPosition;
+    /** Effective snapping configuration. */
+    config(): SnappingConfig;
+    /** Merge configuration changes (writes through to the bound model). */
+    setConfig(config: Partial<SnappingConfig>): void;
+    /**
+     * Apply `geometry` to the bound sketch model with its active vertex
+     * replaced by the current snap position (no-op replacement when the
+     * pointer is not snapped). Returns `true` when the model accepted the
+     * geometry.
+     */
+    applySketchGeometry(tool: EditSketchTool, geometry: Record<string, unknown> | null): boolean;
+    /** Detach event handlers and remove the indicator layer. */
+    remove(): void;
+}
+/**
+ * Bind edit-sketch snapping to a MapLibre-shaped map.
+ *
+ * @example
+ * ```ts
+ * const index = createSnapIndex();
+ * index.setSourceFeatures("parcels", parcels);
+ * const snapping = bindEditSketchSnapping(map, {
+ *   index,
+ *   model: workflow,
+ *   onSnap: ({ candidate }) => showGuide(candidate),
+ * });
+ * map.on("click", (e) => {
+ *   snapping.applySketchGeometry("point", { type: "Point", coordinates: [e.lngLat.lng, e.lngLat.lat] });
+ * });
+ * ```
+ */
+export declare function bindEditSketchSnapping<T = Record<string, unknown>>(map: SnappingMap, options: BindEditSketchSnappingOptions<T>): EditSketchSnappingHandle;
+//# sourceMappingURL=edit-snapping.d.ts.map

package/runtime/edit-snapping.d.ts.map

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

package/runtime/edit-snapping.js

@@ -0,0 +1,190 @@
+/**
+ * MapLibre runtime binding for edit-sketch snapping.
+ *
+ * Wires pointer-move on a MapLibre-shaped map to the renderer-neutral
+ * snapping engine in `contract/edit-snapping.ts`, applies snapped
+ * coordinates to an `EditSketchWorkflowModel`, surfaces snapped / unsnapped
+ * events, and maintains a default visual indicator via a lightweight GeoJSON
+ * circle layer.
+ *
+ * The map interfaces are duck-typed (same pattern as
+ * `interactions/feature-state.ts`) so the SDK carries no hard runtime
+ * dependency on `maplibre-gl`.
+ *
+ * @module
+ */
+import { resolveSnapCandidate, resolveSnappingConfig, withSnappedActiveVertex, } from "../contract/edit-snapping.js";
+const DEFAULT_INDICATOR_ID = "honua-snap-indicator";
+const DEFAULT_INDICATOR_PAINT = Object.freeze({
+    "circle-radius": 6,
+    "circle-color": ["match", ["get", "kind"], "vertex", "#2563eb", "edge", "#0891b2", "#64748b"],
+    "circle-opacity": 0.9,
+    "circle-stroke-color": "#ffffff",
+    "circle-stroke-width": 2,
+});
+/**
+ * Bind edit-sketch snapping to a MapLibre-shaped map.
+ *
+ * @example
+ * ```ts
+ * const index = createSnapIndex();
+ * index.setSourceFeatures("parcels", parcels);
+ * const snapping = bindEditSketchSnapping(map, {
+ *   index,
+ *   model: workflow,
+ *   onSnap: ({ candidate }) => showGuide(candidate),
+ * });
+ * map.on("click", (e) => {
+ *   snapping.applySketchGeometry("point", { type: "Point", coordinates: [e.lngLat.lng, e.lngLat.lat] });
+ * });
+ * ```
+ */
+export function bindEditSketchSnapping(map, options) {
+    const { index, model } = options;
+    let localConfig = resolveSnappingConfig(options.config);
+    const effectiveConfig = () => (model && !options.config ? model.snappingConfig() : localConfig);
+    const pointerEvent = options.pointerEvent ?? "mousemove";
+    const indicator = normalizeIndicatorOptions(options.indicator);
+    const indicatorInstalled = indicator.enabled ? installIndicator(map, indicator) : false;
+    let current;
+    const project = (position) => {
+        const projected = map.project([position[0], position[1]]);
+        return { x: projected.x, y: projected.y };
+    };
+    const resolve = (input) => resolveSnapCandidate(index, { point: input.point, position: input.position, project }, effectiveConfig());
+    const applyResolution = (resolution) => {
+        const previous = current;
+        current = resolution.candidate;
+        if (indicatorInstalled)
+            updateIndicator(map, indicator.id, current);
+        if (current) {
+            if (!previous || !sameCandidate(previous, current))
+                options.onSnap?.(resolution);
+        }
+        else if (previous) {
+            options.onUnsnap?.(previous);
+        }
+    };
+    const onPointerMove = (...args) => {
+        const input = pointerInput(args[0]);
+        if (!input)
+            return;
+        applyResolution(resolve(input));
+    };
+    map.on(pointerEvent, onPointerMove);
+    return {
+        get current() {
+            return current;
+        },
+        resolve(input) {
+            const resolution = resolve(input);
+            applyResolution(resolution);
+            return resolution;
+        },
+        snapPosition(position) {
+            const resolution = resolve({ point: project(position), position });
+            return resolution.candidate ? resolution.candidate.position : position;
+        },
+        config() {
+            return effectiveConfig();
+        },
+        setConfig(config) {
+            if (model)
+                model.setSnapping(config);
+            localConfig = resolveSnappingConfig({ ...localConfig, ...config });
+            // Disabling snapping must not leave a stale snap target behind: clear
+            // the current candidate, indicator, and fire onUnsnap.
+            if (!effectiveConfig().enabled && current) {
+                applyResolution({ snapped: false, candidates: [] });
+            }
+        },
+        applySketchGeometry(tool, geometry) {
+            if (!model)
+                return false;
+            // Gate on the effective config so a snap acquired before snapping was
+            // disabled (e.g. directly via model.setSnapping) is never applied.
+            const active = effectiveConfig().enabled ? current : undefined;
+            const snapped = active ? withSnappedActiveVertex(geometry, active.position) : geometry;
+            const capability = model.setSketchGeometry(tool, snapped).toolCapability(tool);
+            return capability.state === "supported";
+        },
+        remove() {
+            map.off(pointerEvent, onPointerMove);
+            if (indicatorInstalled)
+                removeIndicator(map, indicator.id);
+            current = undefined;
+        },
+    };
+}
+function normalizeIndicatorOptions(input) {
+    const options = typeof input === "object" ? input : {};
+    return {
+        enabled: input === false ? false : (options.enabled ?? true),
+        id: options.id ?? DEFAULT_INDICATOR_ID,
+        paint: { ...DEFAULT_INDICATOR_PAINT, ...(options.paint ?? {}) },
+        ...(options.beforeId ? { beforeId: options.beforeId } : {}),
+    };
+}
+function installIndicator(map, options) {
+    if (!map.addSource || !map.addLayer)
+        return false;
+    if (!map.getSource?.(options.id)) {
+        map.addSource(options.id, { type: "geojson", data: emptyIndicatorData() });
+    }
+    if (!map.getLayer?.(options.id)) {
+        map.addLayer({ id: options.id, type: "circle", source: options.id, paint: options.paint }, options.beforeId);
+    }
+    return true;
+}
+function updateIndicator(map, id, candidate) {
+    const source = map.getSource?.(id);
+    source?.setData?.(candidate ? indicatorData(candidate) : emptyIndicatorData());
+}
+function removeIndicator(map, id) {
+    if (map.getLayer?.(id))
+        map.removeLayer?.(id);
+    if (map.getSource?.(id))
+        map.removeSource?.(id);
+}
+function emptyIndicatorData() {
+    return { type: "FeatureCollection", features: [] };
+}
+function indicatorData(candidate) {
+    return {
+        type: "FeatureCollection",
+        features: [
+            {
+                type: "Feature",
+                geometry: { type: "Point", coordinates: [candidate.position[0], candidate.position[1]] },
+                properties: {
+                    kind: candidate.kind,
+                    sourceId: candidate.sourceId,
+                    featureId: candidate.featureId,
+                    ...(candidate.vertexIndex !== undefined ? { vertexIndex: candidate.vertexIndex } : {}),
+                    ...(candidate.segmentIndex !== undefined ? { segmentIndex: candidate.segmentIndex } : {}),
+                },
+            },
+        ],
+    };
+}
+function sameCandidate(a, b) {
+    return (a.kind === b.kind &&
+        a.sourceId === b.sourceId &&
+        a.featureId === b.featureId &&
+        a.vertexIndex === b.vertexIndex &&
+        a.segmentIndex === b.segmentIndex &&
+        a.position[0] === b.position[0] &&
+        a.position[1] === b.position[1]);
+}
+function pointerInput(event) {
+    if (!event || typeof event !== "object")
+        return undefined;
+    const candidate = event;
+    const point = candidate.point;
+    const lngLat = candidate.lngLat;
+    if (typeof point?.x !== "number" || typeof point.y !== "number")
+        return undefined;
+    if (typeof lngLat?.lng !== "number" || typeof lngLat.lat !== "number")
+        return undefined;
+    return { point: { x: point.x, y: point.y }, position: [lngLat.lng, lngLat.lat] };
+}

package/runtime/errors.d.ts

@@ -6,6 +6,7 @@
  *
  * @module
  */
+import { type HonuaErrorMetadata, HonuaSdkError } from "../core/error-envelope.js";
 /**
  * Stage of the runtime pipeline a failure occurred in. Keeping this as a
  * string union lets callers switch on it without a dependency on the
@@ -25,7 +26,7 @@ export type HonuaMapPackageErrorStage = "fetch" | "load" | "validate" | "update"
  * query-time rejections forwarded by mixed-source consumers — see
  * `docs/composition.md`.
  */
-export declare class HonuaMapPackageError extends Error {
+export declare class HonuaMapPackageError extends HonuaSdkError {
     readonly packageId: string | undefined;
     readonly stage: HonuaMapPackageErrorStage;
     readonly detail: unknown;
@@ -35,6 +36,6 @@ export declare class HonuaMapPackageError extends Error {
         stage: HonuaMapPackageErrorStage;
         detail?: unknown;
         cause?: unknown;
-    });
+    } & HonuaErrorMetadata);
 }
 //# sourceMappingURL=errors.d.ts.map

package/runtime/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/runtime/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GACjC,OAAO,GACP,MAAM,GACN,UAAU,GACV,QAAQ,GACR,eAAe,GACf,aAAa,GACb,MAAM,GACN,OAAO,GACP,SAAS,CAAC;AAEd;;;;;;;;;;;;GAYG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,SAAgB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,SAAgB,KAAK,EAAE,yBAAyB,CAAC;IACjD,SAAgB,MAAM,EAAE,OAAO,CAAC;IAChC,SAAyB,KAAK,EAAE,OAAO,CAAC;gBAGtC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,yBAAyB,CAAC;QACjC,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CASJ"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/runtime/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,kBAAkB,EAAE,aAAa,EAA0B,MAAM,2BAA2B,CAAC;AAE3G;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GACjC,OAAO,GACP,MAAM,GACN,UAAU,GACV,QAAQ,GACR,eAAe,GACf,aAAa,GACb,MAAM,GACN,OAAO,GACP,SAAS,CAAC;AAEd;;;;;;;;;;;;GAYG;AACH,qBAAa,oBAAqB,SAAQ,aAAa;IACrD,SAAgB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,SAAgB,KAAK,EAAE,yBAAyB,CAAC;IACjD,SAAgB,MAAM,EAAE,OAAO,CAAC;IAChC,SAAyB,KAAK,EAAE,OAAO,CAAC;gBAGtC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,yBAAyB,CAAC;QACjC,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,GAAG,kBAAkB;CAczB"}