@honua/app-platform 0.0.20-alpha.0

package/runtime/runtime.js

@@ -0,0 +1,1147 @@
+/**
+ * `HonuaMapRuntime` — the operational API surface `#22` mixed-protocol
+ * composition and `#29` operator components compose on top of. The
+ * runtime never instantiates a MapLibre `Map`; the host passes one in.
+ *
+ * Types use a duck-typed `MaplibreMap` so the SDK stays bundle-neutral
+ * and does not hard-couple to a specific maplibre-gl version.
+ *
+ * @module
+ */
+import { loadQueryTileFeatureDetail } from "../contract/index.js";
+import { bindMapSelectionToExploration, syncFeatureStateSelection } from "../interactions/exploration-bindings.js";
+import { createHoverHandler, createSelectionHandler } from "../interactions/feature-state.js";
+import { hitTestMap } from "../interactions/hit-test.js";
+import { diffPackages } from "./diff.js";
+import { HonuaMapPackageError } from "./errors.js";
+import { buildLegend } from "./legend.js";
+import { bindPopup } from "./popups.js";
+import { featureStateTargetFromSelection, materializeRuntimeLayer, materializeRuntimeSource, materializeStyleValue, protocolForSource, rendererRuntimeDiagnosticError, resolveFeatureIdFromEventFeature, resolveRuntimeBeforeId, selectionTargetForLayer, sourceContextForLayer, throwRuntimeDiagnostics, validateRuntimeFilterExpression, validateRuntimeLayer, validateRuntimeSource, validateRuntimeStyleExpression, } from "./style-interactions.js";
+// ── Runtime ──────────────────────────────────────────────────
+export class HonuaMapRuntime {
+    map;
+    #packageRef;
+    #listeners = new Set();
+    #telemetry;
+    #popupFactory;
+    #popupRenderer;
+    #styleSpecValidationMode;
+    #popupBindings = new Map();
+    #reload;
+    #honuaMap;
+    #dataset;
+    #composedStyle;
+    #disposed = false;
+    /** @internal — constructed by {@link loadMapPackage}. */
+    constructor(internals) {
+        this.map = internals.map;
+        this.#honuaMap = internals.honuaMap;
+        this.#dataset = internals.dataset;
+        this.#composedStyle = internals.composedStyle;
+        this.#packageRef = internals.packageRef;
+        this.#telemetry = internals.telemetry;
+        this.#popupFactory = internals.popupFactory;
+        this.#popupRenderer = internals.popupRenderer;
+        this.#styleSpecValidationMode = internals.styleSpecValidationMode;
+        this.#reload = internals.reload;
+    }
+    /**
+     * The `HonuaMap` owning the current package's sources and layers. The
+     * reference is replaced after every successful `updatePackage` call so
+     * consumers always observe the live source and layer specs rather than
+     * the ones captured at first load.
+     */
+    get honuaMap() {
+        return this.#honuaMap;
+    }
+    /**
+     * The `Dataset` bound to the current package's source bindings. The
+     * reference is replaced after every successful `updatePackage` call so
+     * a source-binding locator or filter change is visible through
+     * `runtime.dataset.source(id)`.
+     */
+    get dataset() {
+        return this.#dataset;
+    }
+    /** The currently applied package. */
+    get mapPackage() {
+        return this.#packageRef.current;
+    }
+    /** The composed MapLibre style last handed to the underlying map. */
+    get composedStyle() {
+        return this.#composedStyle;
+    }
+    // ── Operational API ─────────────────────────────────────────
+    getLegend() {
+        return buildLegend(this.#packageRef.current.legend, this.#composedStyle);
+    }
+    setLayerVisibility(layerId, visible) {
+        this.#assertLive();
+        this.map.setLayoutProperty?.(layerId, "visibility", visible ? "visible" : "none");
+    }
+    validateStyleExpression(value) {
+        return validateRuntimeStyleExpression(value, {
+            styleSpecValidationMode: this.#styleSpecValidationMode,
+        });
+    }
+    validateFilterExpression(filter, layerId) {
+        const layerContext = layerId
+            ? sourceContextForLayer(this.#composedStyle, this.#packageRef.current, layerId)
+            : undefined;
+        return validateRuntimeFilterExpression(filter, {
+            ...(layerId ? { layerId, path: `layers.${layerId}.filter` } : {}),
+            ...(layerContext
+                ? {
+                    sourceId: layerContext.sourceId,
+                    protocol: layerContext.protocol,
+                }
+                : {}),
+            styleSpecValidationMode: this.#styleSpecValidationMode,
+        });
+    }
+    addSource(sourceId, source) {
+        this.#assertLive();
+        const spec = materializeRuntimeSource(source);
+        const diagnostics = [
+            ...(Object.hasOwn(this.#composedStyle.sources, sourceId)
+                ? [
+                    {
+                        code: "source-duplicate",
+                        severity: "error",
+                        message: `Source "${sourceId}" already exists.`,
+                        path: `sources.${sourceId}`,
+                        sourceId,
+                        protocol: spec.type,
+                    },
+                ]
+                : []),
+            ...validateRuntimeSource(sourceId, spec, {
+                style: this.#composedStyle,
+                mapPackage: this.#packageRef.current,
+                operation: "addSource",
+                styleSpecValidationMode: this.#styleSpecValidationMode,
+            }),
+        ];
+        throwRuntimeDiagnostics(diagnostics, `Cannot add source "${sourceId}".`);
+        const nextStyle = {
+            ...this.#composedStyle,
+            sources: { ...this.#composedStyle.sources, [sourceId]: spec },
+        };
+        try {
+            this.#honuaMap.addSource(sourceId, spec);
+            try {
+                this.#applyRendererSourceAdd(sourceId, spec, nextStyle);
+            }
+            catch (error) {
+                this.#honuaMap.removeSource(sourceId);
+                throw error;
+            }
+            this.#composedStyle = nextStyle;
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "HonuaRuntimeDiagnosticError")
+                throw error;
+            throw rendererRuntimeDiagnosticError(`addSource("${sourceId}") failed`, {
+                code: "source-add-failed",
+                message: errorMessage(error),
+                path: `sources.${sourceId}`,
+                sourceId,
+                protocol: spec.type,
+            }, error);
+        }
+    }
+    updateSource(sourceId, source) {
+        this.#assertLive();
+        const previous = this.#composedStyle.sources[sourceId];
+        const spec = materializeRuntimeSource(source);
+        const diagnostics = [
+            ...(!previous
+                ? [
+                    {
+                        code: "source-not-found",
+                        severity: "error",
+                        message: `Source "${sourceId}" does not exist.`,
+                        path: `sources.${sourceId}`,
+                        sourceId,
+                        protocol: spec.type,
+                    },
+                ]
+                : []),
+            ...validateRuntimeSource(sourceId, spec, {
+                style: this.#composedStyle,
+                mapPackage: this.#packageRef.current,
+                operation: "updateSource",
+                styleSpecValidationMode: this.#styleSpecValidationMode,
+            }),
+        ];
+        throwRuntimeDiagnostics(diagnostics, `Cannot update source "${sourceId}".`);
+        const nextStyle = {
+            ...this.#composedStyle,
+            sources: { ...this.#composedStyle.sources, [sourceId]: spec },
+        };
+        try {
+            this.#honuaMap.updateSource(sourceId, spec);
+            try {
+                this.map.setStyle(nextStyle, { diff: true });
+            }
+            catch (error) {
+                if (previous)
+                    this.#honuaMap.updateSource(sourceId, previous);
+                throw error;
+            }
+            this.#composedStyle = nextStyle;
+        }
+        catch (error) {
+            throw rendererRuntimeDiagnosticError(`updateSource("${sourceId}") failed`, {
+                code: "source-update-failed",
+                message: errorMessage(error),
+                path: `sources.${sourceId}`,
+                sourceId,
+                protocol: spec.type,
+            }, error);
+        }
+    }
+    removeSource(sourceId) {
+        this.#assertLive();
+        if (!Object.hasOwn(this.#composedStyle.sources, sourceId)) {
+            return [];
+        }
+        const removedLayerIds = this.#composedStyle.layers
+            .filter((layer) => layer.source === sourceId)
+            .map((layer) => layer.id);
+        const nextSources = { ...this.#composedStyle.sources };
+        delete nextSources[sourceId];
+        const nextStyle = {
+            ...this.#composedStyle,
+            sources: nextSources,
+            layers: this.#composedStyle.layers.filter((layer) => layer.source !== sourceId),
+        };
+        try {
+            this.#applyRendererSourceRemove(sourceId, removedLayerIds, nextStyle);
+            this.#honuaMap.removeSource(sourceId);
+            this.#composedStyle = nextStyle;
+            return removedLayerIds;
+        }
+        catch (error) {
+            throw rendererRuntimeDiagnosticError(`removeSource("${sourceId}") failed`, {
+                code: "source-remove-failed",
+                message: errorMessage(error),
+                path: `sources.${sourceId}`,
+                sourceId,
+            }, error);
+        }
+    }
+    addLayer(layer, order) {
+        this.#assertLive();
+        const spec = materializeRuntimeLayer(layer);
+        const orderResult = resolveRuntimeBeforeId(this.#composedStyle, order);
+        const diagnostics = [
+            ...(this.#composedStyle.layers.some((entry) => entry.id === spec.id)
+                ? [
+                    {
+                        code: "layer-duplicate",
+                        severity: "error",
+                        message: `Layer "${spec.id}" already exists.`,
+                        path: `layers.${spec.id}`,
+                        layerId: spec.id,
+                        sourceId: spec.source,
+                    },
+                ]
+                : []),
+            ...orderResult.diagnostics,
+            ...validateRuntimeLayer(spec, {
+                style: this.#composedStyle,
+                mapPackage: this.#packageRef.current,
+                operation: "addLayer",
+                styleSpecValidationMode: this.#styleSpecValidationMode,
+            }),
+        ];
+        throwRuntimeDiagnostics(diagnostics, `Cannot add layer "${spec.id}".`);
+        const nextStyle = insertLayer(this.#composedStyle, spec, orderResult.beforeId);
+        try {
+            this.#honuaMap.addLayer(spec, orderResult.beforeId);
+            try {
+                this.#applyRendererLayerAdd(spec, orderResult.beforeId, nextStyle);
+            }
+            catch (error) {
+                this.#honuaMap.removeLayer(spec.id);
+                throw error;
+            }
+            this.#composedStyle = nextStyle;
+        }
+        catch (error) {
+            throw rendererRuntimeDiagnosticError(`addLayer("${spec.id}") failed`, {
+                code: "layer-add-failed",
+                message: errorMessage(error),
+                path: `layers.${spec.id}`,
+                sourceId: spec.source,
+                layerId: spec.id,
+                protocol: sourceContextForLayer(nextStyle, this.#packageRef.current, spec.id)?.protocol,
+            }, error);
+        }
+    }
+    updateLayer(layerId, update) {
+        this.#assertLive();
+        const previous = this.#composedStyle.layers.find((layer) => layer.id === layerId);
+        if (!previous) {
+            throwRuntimeDiagnostics([
+                {
+                    code: "layer-not-found",
+                    severity: "error",
+                    message: `Layer "${layerId}" does not exist.`,
+                    path: `layers.${layerId}`,
+                    layerId,
+                },
+            ], `Cannot update layer "${layerId}".`);
+            return;
+        }
+        const { order, ...rawPatch } = update;
+        const patch = materializeStyleValue(rawPatch);
+        const nextLayer = { ...previous, ...patch, id: layerId };
+        const orderResult = resolveRuntimeBeforeId(this.#composedStyle, order, layerId);
+        const diagnostics = [
+            ...orderResult.diagnostics,
+            ...validateRuntimeLayer(nextLayer, {
+                style: this.#composedStyle,
+                mapPackage: this.#packageRef.current,
+                operation: "updateLayer",
+                styleSpecValidationMode: this.#styleSpecValidationMode,
+            }),
+        ];
+        throwRuntimeDiagnostics(diagnostics, `Cannot update layer "${layerId}".`);
+        const nextStyle = replaceLayer(this.#composedStyle, nextLayer, order === undefined ? undefined : orderResult.beforeId, order === undefined);
+        const incremental = order === undefined && canPatchLayerWithMap(this.map, previous, nextLayer);
+        try {
+            if (incremental) {
+                this.#patchLayer(layerId, previous, nextLayer);
+            }
+            else {
+                this.map.setStyle(nextStyle, { diff: true });
+            }
+            this.#honuaMap.updateLayer(layerId, patch);
+            if (order !== undefined) {
+                this.#honuaMap.moveLayer(layerId, orderResult.beforeId);
+            }
+            this.#composedStyle = nextStyle;
+        }
+        catch (error) {
+            throw rendererRuntimeDiagnosticError(`updateLayer("${layerId}") failed`, {
+                code: "layer-update-failed",
+                message: errorMessage(error),
+                path: `layers.${layerId}`,
+                sourceId: nextLayer.source,
+                layerId,
+                protocol: sourceContextForLayer(nextStyle, this.#packageRef.current, layerId)?.protocol,
+            }, error);
+        }
+    }
+    removeLayer(layerId) {
+        this.#assertLive();
+        const existing = this.#composedStyle.layers.find((layer) => layer.id === layerId);
+        if (!existing)
+            return false;
+        const nextStyle = {
+            ...this.#composedStyle,
+            layers: this.#composedStyle.layers.filter((layer) => layer.id !== layerId),
+        };
+        try {
+            if (this.map.removeLayer) {
+                this.map.removeLayer(layerId);
+            }
+            else {
+                this.map.setStyle(nextStyle, { diff: true });
+            }
+            this.#honuaMap.removeLayer(layerId);
+            this.#composedStyle = nextStyle;
+            return true;
+        }
+        catch (error) {
+            throw rendererRuntimeDiagnosticError(`removeLayer("${layerId}") failed`, {
+                code: "layer-remove-failed",
+                message: errorMessage(error),
+                path: `layers.${layerId}`,
+                sourceId: existing.source,
+                layerId,
+                protocol: sourceContextForLayer(this.#composedStyle, this.#packageRef.current, layerId)?.protocol,
+            }, error);
+        }
+    }
+    moveLayer(layerId, order) {
+        this.#assertLive();
+        const existing = this.#composedStyle.layers.find((layer) => layer.id === layerId);
+        if (!existing) {
+            throwRuntimeDiagnostics([
+                {
+                    code: "layer-not-found",
+                    severity: "error",
+                    message: `Layer "${layerId}" does not exist.`,
+                    path: `layers.${layerId}`,
+                    layerId,
+                },
+            ], `Cannot move layer "${layerId}".`);
+            return;
+        }
+        const orderResult = resolveRuntimeBeforeId(this.#composedStyle, order, layerId);
+        throwRuntimeDiagnostics(orderResult.diagnostics, `Cannot move layer "${layerId}".`);
+        const nextStyle = replaceLayer(this.#composedStyle, existing, orderResult.beforeId, false);
+        try {
+            if (this.map.moveLayer) {
+                this.map.moveLayer(layerId, orderResult.beforeId);
+            }
+            else {
+                this.map.setStyle(nextStyle, { diff: true });
+            }
+            this.#honuaMap.moveLayer(layerId, orderResult.beforeId);
+            this.#composedStyle = nextStyle;
+        }
+        catch (error) {
+            throw rendererRuntimeDiagnosticError(`moveLayer("${layerId}") failed`, {
+                code: "layer-move-failed",
+                message: errorMessage(error),
+                path: `layers.${layerId}`,
+                sourceId: existing.source,
+                layerId,
+                protocol: sourceContextForLayer(this.#composedStyle, this.#packageRef.current, layerId)?.protocol,
+            }, error);
+        }
+    }
+    setLayerPaint(layerId, paint) {
+        this.updateLayer(layerId, { paint });
+    }
+    setLayerLayout(layerId, layout) {
+        this.updateLayer(layerId, { layout });
+    }
+    setLayerFilter(layerId, filter) {
+        this.updateLayer(layerId, { filter });
+    }
+    refreshSource(sourceId) {
+        this.#assertLive();
+        if (!Object.hasOwn(this.#composedStyle.sources, sourceId)) {
+            throwRuntimeDiagnostics([
+                {
+                    code: "source-not-found",
+                    severity: "error",
+                    message: `Source "${sourceId}" does not exist.`,
+                    path: `sources.${sourceId}`,
+                    sourceId,
+                },
+            ], `Cannot refresh source "${sourceId}".`);
+            return false;
+        }
+        const source = this.map.getSource?.(sourceId);
+        if (typeof source?.reload !== "function")
+            return false;
+        try {
+            source.reload();
+            this.#emit({ type: "source-ready", sourceId });
+            return true;
+        }
+        catch (error) {
+            throw rendererRuntimeDiagnosticError(`refreshSource("${sourceId}") failed`, {
+                code: "source-refresh-failed",
+                message: errorMessage(error),
+                path: `sources.${sourceId}`,
+                sourceId,
+                protocol: protocolForSource(this.#composedStyle, this.#packageRef.current, sourceId),
+            }, error);
+        }
+    }
+    layerSelectionTarget(layerId, id) {
+        const target = selectionTargetForLayer(this.#composedStyle, layerId, id);
+        if (!target) {
+            throwRuntimeDiagnostics([
+                {
+                    code: "layer-source-missing",
+                    severity: "error",
+                    message: `Layer "${layerId}" does not have a source for feature selection.`,
+                    path: `layers.${layerId}.source`,
+                    layerId,
+                },
+            ], `Cannot build a source-qualified selection target for layer "${layerId}".`);
+            throw new Error("unreachable");
+        }
+        return target;
+    }
+    setFeatureStateForTarget(target, state) {
+        this.#assertLive();
+        this.map.setFeatureState(normalizeFeatureStateTarget(target), state);
+    }
+    getFeatureStateForTarget(target) {
+        this.#assertLive();
+        return this.map.getFeatureState(normalizeFeatureStateTarget(target));
+    }
+    removeFeatureStateForTarget(target, key) {
+        this.#assertLive();
+        this.map.removeFeatureState(normalizeFeatureStateTarget(target), key);
+    }
+    bindHover(layerId, options = {}) {
+        this.#assertLive();
+        const context = this.#interactionContext(layerId, options.sourceId, options.sourceLayer);
+        return createHoverHandler(this.map, {
+            source: context.sourceId,
+            sourceLayer: context.sourceLayer,
+            layer: layerId,
+            stateKey: options.stateKey,
+        });
+    }
+    bindClick(layerId, handler, options = {}) {
+        this.#assertLive();
+        const context = this.#interactionContext(layerId, options.sourceId, options.sourceLayer);
+        const onClick = (event) => {
+            const feature = firstEventFeature(event);
+            const featureId = feature ? resolveFeatureIdFromEventFeature(feature, event, options) : undefined;
+            handler({
+                type: "click",
+                layerId,
+                sourceId: context.sourceId,
+                sourceLayer: context.sourceLayer,
+                feature,
+                featureId,
+                ...(featureId !== undefined
+                    ? {
+                        selectionTarget: {
+                            sourceId: context.sourceId,
+                            id: featureId,
+                            ...(context.sourceLayer !== undefined ? { sourceLayer: context.sourceLayer } : {}),
+                        },
+                    }
+                    : {}),
+                originalEvent: event,
+            });
+        };
+        this.map.on("click", layerId, onClick);
+        return {
+            remove: () => this.map.off("click", layerId, onClick),
+        };
+    }
+    async hitTest(input, options = {}) {
+        this.#assertLive();
+        return hitTestMap(this.map, input, {
+            ...options,
+            featureContexts: this.#hitFeatureContexts(options.layers),
+            detailLoader: options.loadDetails
+                ? (context, detailOptions) => this.#loadHitDetail(context, detailOptions, options)
+                : undefined,
+        });
+    }
+    onPointer(handler, options = {}) {
+        this.#assertLive();
+        const eventName = options.event ?? "click";
+        const onPointer = (event) => {
+            void this.hitTest(event, options).then((hit) => {
+                const pointer = {
+                    type: eventName,
+                    point: hit.point,
+                    ...(hit.lngLat ? { lngLat: hit.lngLat } : {}),
+                    originalEvent: event,
+                };
+                return handler(pointer, hit);
+            });
+        };
+        this.map.on(eventName, onPointer);
+        return {
+            remove: () => this.map.off(eventName, onPointer),
+        };
+    }
+    bindSelect(layerId, options = {}) {
+        this.#assertLive();
+        const context = this.#interactionContext(layerId, options.sourceId, options.sourceLayer);
+        return createSelectionHandler(this.map, {
+            source: context.sourceId,
+            sourceLayer: context.sourceLayer,
+            layer: layerId,
+            stateKey: options.stateKey,
+            multiSelect: options.multiSelect,
+            onChange: options.onChange,
+            onSelectionTargetsChange: options.onSelectionTargetsChange,
+        });
+    }
+    bindSelectionToExploration(layerId, view, options = {}) {
+        this.#assertLive();
+        const context = this.#interactionContext(layerId, options.sourceId, options.sourceLayer);
+        return bindMapSelectionToExploration(this.map, view, {
+            source: context.sourceId,
+            sourceLayer: context.sourceLayer,
+            layer: layerId,
+            stateKey: options.stateKey,
+            multiSelect: options.multiSelect,
+            onChange: options.onChange,
+            onSelectionTargetsChange: options.onSelectionTargetsChange,
+            replaceSelection: options.replaceSelection,
+        });
+    }
+    syncSelectionFromExploration(layerId, view, options = {}) {
+        this.#assertLive();
+        const context = this.#interactionContext(layerId, options.sourceId, options.sourceLayer);
+        return syncFeatureStateSelection(this.map, view, {
+            source: context.sourceId,
+            sourceLayer: context.sourceLayer,
+            stateKey: options.stateKey,
+        });
+    }
+    bindPopup(layerId, binding) {
+        this.#assertLive();
+        if (!this.#popupFactory) {
+            throw new HonuaMapPackageError("bindPopup requires opts.popupFactory to be set on loadMapPackage", {
+                packageId: this.#packageRef.current.mapPackageId,
+                stage: "popup",
+                detail: { layerId },
+            });
+        }
+        const sourceId = layerIdToSource(this.#composedStyle, layerId);
+        const resolvedFromPackage = binding === undefined;
+        const resolved = binding ?? popupBindingForSource(this.#packageRef.current, sourceId);
+        if (!resolved) {
+            throw new HonuaMapPackageError(`no popupBinding found for layer "${layerId}"; supply a binding argument or add one to MapPackage.popupBindings`, { packageId: this.#packageRef.current.mapPackageId, stage: "popup", detail: { layerId } });
+        }
+        this.#popupBindings.get(layerId)?.handle.remove();
+        const handle = bindPopup(this.map, {
+            binding: resolved,
+            layerId,
+            popupFactory: this.#popupFactory,
+            render: this.#popupRenderer,
+        });
+        this.#popupBindings.set(layerId, { handle, sourceId, binding: resolved, resolvedFromPackage });
+        return {
+            remove: () => {
+                handle.remove();
+                if (this.#popupBindings.get(layerId)?.handle === handle) {
+                    this.#popupBindings.delete(layerId);
+                }
+            },
+        };
+    }
+    setViewState(view) {
+        this.#assertLive();
+        const bbox = view.bbox ?? this.#packageRef.current.initialView?.bbox;
+        if (view.bbox && this.map.fitBounds) {
+            const [west, south, east, north] = view.bbox;
+            this.map.fitBounds([
+                [west, south],
+                [east, north],
+            ], {
+                animate: view.animate ?? false,
+                ...(view.padding !== undefined ? { padding: view.padding } : {}),
+            });
+            return;
+        }
+        if (view.center) {
+            this.map.jumpTo?.({
+                center: view.center,
+                ...(view.zoom !== undefined ? { zoom: view.zoom } : {}),
+                ...(view.bearing !== undefined ? { bearing: view.bearing } : {}),
+                ...(view.pitch !== undefined ? { pitch: view.pitch } : {}),
+            });
+            return;
+        }
+        if (bbox && this.map.fitBounds) {
+            const [west, south, east, north] = bbox;
+            this.map.fitBounds([
+                [west, south],
+                [east, north],
+            ], { animate: false });
+        }
+    }
+    /**
+     * Diff the current package against `next`. Applies the change
+     * incrementally when safe; falls back to `map.setStyle` for structural
+     * changes. Preserves unknown fields from `next` on round-trip.
+     */
+    async updatePackage(next) {
+        this.#assertLive();
+        const span = this.#startSpan("update", next.mapPackageId, { previousId: this.#packageRef.current.mapPackageId });
+        try {
+            if (next.format !== this.#packageRef.current.format) {
+                throw new HonuaMapPackageError(`updatePackage: format "${next.format}" is incompatible with "${this.#packageRef.current.format}"`, {
+                    packageId: next.mapPackageId,
+                    stage: "update",
+                    detail: { expected: this.#packageRef.current.format, received: next.format },
+                });
+            }
+            let diff = diffPackages(this.#packageRef.current, next);
+            const reload = await this.#reload(next);
+            const composedStructuralReason = diff.incremental
+                ? detectUnpatchableLayerChange(this.map, this.#composedStyle, reload.composed)
+                : undefined;
+            if (composedStructuralReason) {
+                diff = {
+                    ...diff,
+                    incremental: false,
+                    structuralReason: composedStructuralReason,
+                };
+            }
+            if (!diff.incremental) {
+                // setStyle first so a host-map failure leaves the previous
+                // runtime state intact. Only after it succeeds do we clear the
+                // old HonuaMap, swap in the new dataset / honuaMap, and tear
+                // down popup bindings whose layer, source, or package binding
+                // changed.
+                const previousHonuaMap = this.#honuaMap;
+                this.map.setStyle(reload.composed);
+                previousHonuaMap.clear();
+                this.#honuaMap = reload.honuaMap;
+                this.#dataset = reload.dataset;
+                this.#packageRef.current = next;
+                this.#composedStyle = reload.composed;
+                this.#reapPopupBindings(reload.composed, next);
+                this.#emit({ type: "package-updated", packageId: next.mapPackageId, diff });
+                this.#emitReloadFailures(reload.failedSources);
+                this.#finishSpan(span);
+                return;
+            }
+            this.#applyIncremental(reload.composed, diff);
+            this.#honuaMap = reload.honuaMap;
+            this.#dataset = reload.dataset;
+            this.#packageRef.current = next;
+            this.#composedStyle = reload.composed;
+            this.#reapPopupBindings(reload.composed, next);
+            this.#emit({ type: "package-updated", packageId: next.mapPackageId, diff });
+            this.#emitReloadFailures(reload.failedSources);
+            this.#finishSpan(span);
+        }
+        catch (error) {
+            this.#finishSpan(span, error);
+            if (error instanceof HonuaMapPackageError)
+                throw error;
+            throw new HonuaMapPackageError("updatePackage failed", {
+                packageId: next.mapPackageId,
+                stage: "update",
+                cause: error,
+            });
+        }
+    }
+    on(listener) {
+        this.#listeners.add(listener);
+        return {
+            remove: () => {
+                this.#listeners.delete(listener);
+            },
+        };
+    }
+    /** @internal used by the loader to emit `package-loaded`. */
+    _emit(event) {
+        this.#emit(event);
+    }
+    /**
+     * Surface a per-source failure detected outside the loader path —
+     * typically a query / stream rejection in a mixed-source fan-out
+     * (the canonical consumer is `#29`'s operator components). Emits the
+     * existing `source-error` runtime event so listeners do not have to
+     * subscribe to a parallel error channel and pipes the failure
+     * through {@link HonuaRuntimeTelemetry.error} as a `source-bind`
+     * span if the consumer wired one up.
+     *
+     * Idempotent and side-effect-free outside listener / telemetry
+     * fan-out: the runtime does not retry, suppress, or reshape the
+     * underlying source. Disposed runtimes silently no-op so a late
+     * rejection from a stream never throws inside an event handler.
+     */
+    reportSourceError(sourceId, error) {
+        if (this.#disposed)
+            return;
+        if (this.#telemetry?.error) {
+            const startedAt = Date.now();
+            this.#telemetry.error({
+                kind: "source-bind",
+                packageId: this.#packageRef.current.mapPackageId,
+                startedAt,
+                finishedAt: startedAt,
+                durationMs: 0,
+                detail: { sourceId },
+                error,
+            });
+        }
+        this.#emit({ type: "source-error", sourceId, error });
+    }
+    dispose() {
+        if (this.#disposed)
+            return;
+        const span = this.#startSpan("dispose", this.#packageRef.current.mapPackageId);
+        try {
+            for (const binding of this.#popupBindings.values())
+                binding.handle.remove();
+            this.#popupBindings.clear();
+            for (const layer of this.#composedStyle.layers) {
+                this.map.removeLayer?.(layer.id);
+            }
+            for (const sourceId of Object.keys(this.#composedStyle.sources)) {
+                this.map.removeSource?.(sourceId);
+            }
+            this.#honuaMap.clear();
+            this.#emit({ type: "disposed", packageId: this.#packageRef.current.mapPackageId });
+            this.#listeners.clear();
+            this.#disposed = true;
+            this.#finishSpan(span);
+        }
+        catch (error) {
+            this.#finishSpan(span, error);
+            throw error;
+        }
+    }
+    // ── Private helpers ─────────────────────────────────────────
+    #applyRendererSourceAdd(sourceId, source, nextStyle) {
+        if (this.map.addSource) {
+            this.map.addSource(sourceId, source);
+            return;
+        }
+        this.map.setStyle(nextStyle, { diff: true });
+    }
+    #applyRendererSourceRemove(sourceId, removedLayerIds, nextStyle) {
+        if (!this.map.removeLayer || !this.map.removeSource) {
+            this.map.setStyle(nextStyle, { diff: true });
+            return;
+        }
+        for (const layerId of [...removedLayerIds].reverse()) {
+            this.map.removeLayer(layerId);
+        }
+        this.map.removeSource(sourceId);
+    }
+    #applyRendererLayerAdd(layer, beforeId, nextStyle) {
+        if (this.map.addLayer) {
+            this.map.addLayer(layer, beforeId);
+            return;
+        }
+        this.map.setStyle(nextStyle, { diff: true });
+    }
+    #interactionContext(layerId, sourceIdOverride, sourceLayerOverride) {
+        const context = sourceContextForLayer(this.#composedStyle, this.#packageRef.current, layerId);
+        const sourceId = sourceIdOverride ?? context?.sourceId;
+        if (!sourceId) {
+            throwRuntimeDiagnostics([
+                {
+                    code: "layer-source-missing",
+                    severity: "error",
+                    message: `Layer "${layerId}" does not have a source for interactions.`,
+                    path: `layers.${layerId}.source`,
+                    layerId,
+                },
+            ], `Cannot bind interactions for layer "${layerId}".`);
+            throw new Error("unreachable");
+        }
+        return {
+            sourceId,
+            sourceLayer: sourceLayerOverride ?? context?.sourceLayer,
+            protocol: context?.protocol,
+        };
+    }
+    #hitFeatureContexts(layerIds) {
+        const contexts = {};
+        const layers = layerIds
+            ? this.#composedStyle.layers.filter((layer) => layerIds.includes(layer.id))
+            : this.#composedStyle.layers;
+        for (const layer of layers) {
+            const context = sourceContextForLayer(this.#composedStyle, this.#packageRef.current, layer.id);
+            contexts[layer.id] = {
+                layerId: layer.id,
+                layerType: layer.type,
+                sourceId: context?.sourceId,
+                sourceLayer: context?.sourceLayer,
+                protocol: context?.protocol,
+            };
+        }
+        return contexts;
+    }
+    async #loadHitDetail(context, options, hitTestOptions) {
+        const source = this.#dataset.source(context.target.sourceId);
+        if (!source)
+            return undefined;
+        const descriptor = hitTestOptions.queryTileSources?.[context.target.sourceId];
+        if (descriptor) {
+            return loadQueryTileFeatureDetail({
+                source,
+                descriptor,
+                target: context.target,
+                signal: options.signal,
+            });
+        }
+        const idField = firstString(hitTestOptions.featureIdProperty, context.hit.properties.OBJECTID !== undefined
+            ? "OBJECTID"
+            : context.hit.properties.objectid !== undefined
+                ? "objectid"
+                : context.hit.properties.ObjectID !== undefined
+                    ? "ObjectID"
+                    : context.hit.properties.id !== undefined
+                        ? "id"
+                        : undefined);
+        if (!idField)
+            return undefined;
+        const result = await source.query({
+            where: `${idField} = ${sqlLiteral(context.target.id)}`,
+            returnGeometry: true,
+            pagination: { limit: 1 },
+            signal: options.signal,
+        });
+        return result.features[0];
+    }
+    #applyIncremental(composed, diff) {
+        const prevStyle = this.#composedStyle;
+        for (const layerId of diff.removedLayerIds) {
+            this.#honuaMap.removeLayer(layerId);
+            this.map.removeLayer?.(layerId);
+        }
+        const prevLayers = new Map(prevStyle.layers.map((l) => [l.id, l]));
+        const nextLayers = new Map(composed.layers.map((l) => [l.id, l]));
+        for (const layerId of diff.changedLayerIds) {
+            const nextLayer = nextLayers.get(layerId);
+            const prevLayer = prevLayers.get(layerId);
+            if (!nextLayer || !prevLayer)
+                continue;
+            this.#patchLayer(layerId, prevLayer, nextLayer);
+        }
+        for (const layerId of prevLayers.keys()) {
+            if (diff.removedLayerIds.includes(layerId) || diff.changedLayerIds.includes(layerId))
+                continue;
+            const nextLayer = nextLayers.get(layerId);
+            const prevLayer = prevLayers.get(layerId);
+            if (!nextLayer || !prevLayer)
+                continue;
+            if (!shallowPaintLayoutEqual(prevLayer, nextLayer)) {
+                this.#patchLayer(layerId, prevLayer, nextLayer);
+            }
+        }
+    }
+    #patchLayer(layerId, prev, next) {
+        const prevPaint = prev.paint ?? {};
+        const nextPaint = next.paint ?? {};
+        if (!this.map.setPaintProperty && !sameJson(prevPaint, nextPaint)) {
+            throw new Error(`Renderer cannot patch paint properties for layer "${layerId}".`);
+        }
+        if (this.map.setPaintProperty) {
+            const keys = unionKeys(prevPaint, nextPaint);
+            for (const key of keys) {
+                const prevValue = prevPaint[key];
+                const nextValue = Object.hasOwn(nextPaint, key) ? nextPaint[key] : undefined;
+                if (prevValue === nextValue)
+                    continue;
+                this.map.setPaintProperty(layerId, key, nextValue);
+            }
+        }
+        const prevLayout = prev.layout ?? {};
+        const nextLayout = next.layout ?? {};
+        if (!this.map.setLayoutProperty && !sameJson(prevLayout, nextLayout)) {
+            throw new Error(`Renderer cannot patch layout properties for layer "${layerId}".`);
+        }
+        if (this.map.setLayoutProperty) {
+            const keys = unionKeys(prevLayout, nextLayout);
+            for (const key of keys) {
+                const prevValue = prevLayout[key];
+                const nextValue = Object.hasOwn(nextLayout, key) ? nextLayout[key] : undefined;
+                if (prevValue === nextValue)
+                    continue;
+                this.map.setLayoutProperty(layerId, key, nextValue);
+            }
+        }
+        if (!this.map.setFilter && !sameJson(prev.filter, next.filter)) {
+            throw new Error(`Renderer cannot patch filter for layer "${layerId}".`);
+        }
+        if (this.map.setFilter && !sameJson(prev.filter, next.filter)) {
+            this.map.setFilter(layerId, next.filter);
+        }
+    }
+    #reapPopupBindings(composed, pkg) {
+        if (this.#popupBindings.size === 0)
+            return;
+        for (const [layerId, active] of Array.from(this.#popupBindings)) {
+            const nextSourceId = layerIdToSource(composed, layerId);
+            const packageBindingChanged = active.resolvedFromPackage && !sameJson(active.binding, popupBindingForSource(pkg, nextSourceId));
+            if (!nextSourceId || nextSourceId !== active.sourceId || packageBindingChanged) {
+                active.handle.remove();
+                this.#popupBindings.delete(layerId);
+            }
+        }
+    }
+    #emit(event) {
+        for (const listener of this.#listeners)
+            listener(event);
+    }
+    #emitReloadFailures(failures) {
+        if (!failures || failures.length === 0)
+            return;
+        for (const failure of failures) {
+            this.#emit({ type: "source-error", sourceId: failure.sourceId, error: failure.error });
+        }
+    }
+    #assertLive() {
+        if (this.#disposed) {
+            throw new HonuaMapPackageError("runtime is disposed", {
+                packageId: this.#packageRef.current.mapPackageId,
+                stage: "dispose",
+            });
+        }
+    }
+    #startSpan(kind, packageId, detail) {
+        const span = { kind, packageId, startedAt: Date.now(), detail };
+        this.#telemetry?.before?.(span);
+        return span;
+    }
+    #finishSpan(span, error) {
+        const finishedAt = Date.now();
+        const result = {
+            ...span,
+            finishedAt,
+            durationMs: finishedAt - span.startedAt,
+        };
+        if (error !== undefined) {
+            result.error = error;
+            this.#telemetry?.error?.(result);
+        }
+        else {
+            this.#telemetry?.after?.(result);
+        }
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────
+function insertLayer(style, layer, beforeId) {
+    const layers = [...style.layers];
+    if (beforeId) {
+        const index = layers.findIndex((entry) => entry.id === beforeId);
+        if (index >= 0) {
+            layers.splice(index, 0, layer);
+        }
+        else {
+            layers.push(layer);
+        }
+    }
+    else {
+        layers.push(layer);
+    }
+    return { ...style, layers };
+}
+function replaceLayer(style, layer, beforeId, preserveIndexWhenNoBefore = true) {
+    const layers = style.layers.filter((entry) => entry.id !== layer.id);
+    if (beforeId) {
+        const index = layers.findIndex((entry) => entry.id === beforeId);
+        if (index >= 0) {
+            layers.splice(index, 0, layer);
+        }
+        else {
+            layers.push(layer);
+        }
+    }
+    else {
+        const previousIndex = style.layers.findIndex((entry) => entry.id === layer.id);
+        if (preserveIndexWhenNoBefore && previousIndex >= 0 && previousIndex < layers.length) {
+            layers.splice(previousIndex, 0, layer);
+        }
+        else {
+            layers.push(layer);
+        }
+    }
+    return { ...style, layers };
+}
+function normalizeFeatureStateTarget(target) {
+    if ("sourceId" in target) {
+        return featureStateTargetFromSelection(target);
+    }
+    return target;
+}
+function firstEventFeature(event) {
+    if (typeof event !== "object" || event === null || !("features" in event)) {
+        return undefined;
+    }
+    const features = event.features;
+    return Array.isArray(features) ? features[0] : undefined;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function firstString(...values) {
+    return values.find((value) => typeof value === "string" && value.length > 0);
+}
+function sqlLiteral(value) {
+    return typeof value === "number" ? String(value) : `'${value.replaceAll("'", "''")}'`;
+}
+function layerIdToSource(style, layerId) {
+    return style.layers.find((l) => l.id === layerId)?.source;
+}
+function popupBindingForSource(pkg, sourceId) {
+    if (!sourceId)
+        return undefined;
+    return pkg.popupBindings?.find((binding) => binding.sourceId === sourceId);
+}
+function detectUnpatchableLayerChange(map, previous, next) {
+    // Tolerant source failure / recovery on reload can change the composed
+    // layer or source set without showing up in the raw package diff
+    // (which is computed from `mapSpec`, not the post-filter composed
+    // style). Force structural fallback whenever the composed shape
+    // differs so `#applyIncremental` does not leave stale MapLibre layers
+    // or sources behind.
+    const previousLayerIds = previous.layers.map((layer) => layer.id);
+    const nextLayerIds = next.layers.map((layer) => layer.id);
+    if (previousLayerIds.length !== nextLayerIds.length) {
+        return "composed layer set changed (tolerant source failure or recovery)";
+    }
+    for (let i = 0; i < previousLayerIds.length; i++) {
+        if (previousLayerIds[i] !== nextLayerIds[i]) {
+            return "composed layer set or order changed (tolerant source failure or recovery)";
+        }
+    }
+    const previousSourceIds = Object.keys(previous.sources).sort();
+    const nextSourceIds = Object.keys(next.sources).sort();
+    if (previousSourceIds.length !== nextSourceIds.length) {
+        return "composed source set changed (tolerant source failure or recovery)";
+    }
+    for (let i = 0; i < previousSourceIds.length; i++) {
+        if (previousSourceIds[i] !== nextSourceIds[i]) {
+            return "composed source set changed (tolerant source failure or recovery)";
+        }
+    }
+    for (const sourceId of previousSourceIds) {
+        if (!sameJson(previous.sources[sourceId], next.sources[sourceId])) {
+            return `composed source "${sourceId}" changed`;
+        }
+    }
+    const previousLayers = new Map(previous.layers.map((layer) => [layer.id, layer]));
+    for (const nextLayer of next.layers) {
+        const previousLayer = previousLayers.get(nextLayer.id);
+        if (!previousLayer)
+            continue;
+        if (!patchableLayerShapeEqual(previousLayer, nextLayer)) {
+            return `layer "${nextLayer.id}" changed outside paint/layout/filter`;
+        }
+        if (!canPatchLayerWithMap(map, previousLayer, nextLayer)) {
+            return `layer "${nextLayer.id}" requires unsupported incremental patch APIs`;
+        }
+    }
+    return undefined;
+}
+function patchableLayerShapeEqual(a, b) {
+    return (a.type === b.type &&
+        (a.source ?? "") === (b.source ?? "") &&
+        a["source-layer"] === b["source-layer"] &&
+        a.minzoom === b.minzoom &&
+        a.maxzoom === b.maxzoom &&
+        sameJson(a.metadata, b.metadata));
+}
+function canPatchLayerWithMap(map, previous, next) {
+    if (!patchableLayerShapeEqual(previous, next))
+        return false;
+    if (!sameJson(previous.paint ?? {}, next.paint ?? {}) && !map.setPaintProperty)
+        return false;
+    if (!sameJson(previous.layout ?? {}, next.layout ?? {}) && !map.setLayoutProperty)
+        return false;
+    if (!sameJson(previous.filter, next.filter) && !map.setFilter)
+        return false;
+    return true;
+}
+function shallowPaintLayoutEqual(a, b) {
+    return (sameJson(a.paint ?? {}, b.paint ?? {}) && sameJson(a.layout ?? {}, b.layout ?? {}) && sameJson(a.filter, b.filter));
+}
+function unionKeys(a, b) {
+    const seen = new Set();
+    for (const key of Object.keys(a))
+        seen.add(key);
+    for (const key of Object.keys(b))
+        seen.add(key);
+    return [...seen];
+}
+function sameJson(a, b) {
+    if (a === b)
+        return true;
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch {
+        return false;
+    }
+}