@honua/app-platform 0.0.20-alpha.0

package/app-controller/controller.js

@@ -0,0 +1,1173 @@
+import { createExplorationContext, isSourceQualifiedSelectionTarget, sourceFeatureSelectionTarget, } from "../exploration/index.js";
+export const HONUA_CONTROLLER_SNAPSHOT_VERSION = 1;
+export class HonuaControllerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "HonuaControllerError";
+        this.code = code;
+    }
+}
+let generatedOverlayId = 0;
+let generatedAnnotationId = 0;
+export function createHonuaController(runtimeOrOptions = {}) {
+    return new HonuaController(isControllerOptions(runtimeOrOptions) ? runtimeOrOptions : { runtime: runtimeOrOptions });
+}
+export class HonuaController {
+    context;
+    #runtime;
+    #adapter;
+    #ownsContext;
+    #disposeRuntime;
+    #disposeAdapter;
+    #layerSourcePersistence;
+    #listeners = new Map();
+    #subscriptions = [];
+    #layerGroups;
+    #legendItemLayers;
+    #visibility;
+    #viewport;
+    #overlays = new Map();
+    #annotations = new Map();
+    #layerSourceMutations = [];
+    #layerSourceVersion;
+    #layerSourceConcurrencyToken;
+    #disposed = false;
+    #suppressExtentEvent = false;
+    constructor(options = {}) {
+        const internals = resolveInternals(options);
+        this.context = internals.context;
+        this.#runtime = internals.runtime;
+        this.#adapter = internals.adapter;
+        this.#ownsContext = internals.ownsContext;
+        this.#disposeRuntime = internals.disposeRuntime;
+        this.#disposeAdapter = internals.disposeAdapter;
+        this.#layerSourcePersistence = internals.layerSourcePersistence;
+        this.#layerGroups = structuredClone(options.layerGroups ?? {});
+        this.#legendItemLayers = structuredClone(options.legendItemLayers ?? {});
+        this.#visibility = cloneVisibility(internals.initialVisibility);
+        this.#viewport = normalizeViewport(internals.initialViewport);
+        const initialExtent = viewportToExtent(this.#viewport);
+        if (initialExtent && !this.context.state.extent) {
+            this.context.dispatch({ kind: "set-extent", extent: initialExtent });
+        }
+        this.#subscriptions.push(this.context.subscribe("extent", (event) => {
+            if (this.#suppressExtentEvent)
+                return;
+            const previous = this.#viewport;
+            this.#viewport = normalizeViewport({
+                ...this.#viewport,
+                ...extentToViewport(event.state.extent),
+            });
+            if (!viewportsEqual(previous, this.#viewport)) {
+                this.#emit({ type: "viewport-move", viewport: this.getViewport(), previous, source: "exploration" });
+            }
+        }));
+        this.#subscriptions.push(this.context.subscribe("selection", (event) => {
+            this.#emit({
+                type: "selection-change",
+                selection: cloneSelection(event.state.selection),
+                previous: cloneSelection(event.previous.selection),
+                source: "exploration",
+            });
+        }));
+        if (this.#adapter?.onViewportMove) {
+            this.#subscriptions.push(removeAdapterSubscription(this.#adapter.onViewportMove((viewport) => {
+                if (!viewport)
+                    return;
+                this.#commitViewport(viewport, "adapter");
+            })));
+        }
+        if (this.#adapter?.onViewportMoveEnd) {
+            this.#subscriptions.push(removeAdapterSubscription(this.#adapter.onViewportMoveEnd((viewport) => {
+                const previous = this.#viewport;
+                if (viewport)
+                    this.#commitViewport(viewport, "adapter", { emitMove: false });
+                this.#emit({ type: "viewport-move-end", viewport: this.getViewport(), previous, source: "adapter" });
+            })));
+        }
+        if (this.#adapter?.onIdle) {
+            this.#subscriptions.push(removeAdapterSubscription(this.#adapter.onIdle(() => {
+                this.#emit({ type: "idle", snapshot: this.snapshot(), source: "adapter" });
+            })));
+        }
+    }
+    getViewport() {
+        this.#assertLive("getViewport");
+        return cloneViewport({
+            ...this.#adapter?.getViewport?.(),
+            ...this.#viewport,
+            ...extentToViewport(this.context.state.extent),
+        });
+    }
+    setViewport(viewport, options = {}) {
+        this.#assertLive("setViewport");
+        const normalized = normalizeViewport(viewport);
+        const previous = this.getViewport();
+        this.#adapter?.setViewport?.(normalized, options);
+        this.#commitViewport(normalized, "controller");
+        this.#emit({ type: "viewport-move-end", viewport: this.getViewport(), previous, source: "controller" });
+        this.#queueIdle("controller");
+    }
+    fitBounds(bounds, options = {}) {
+        this.#assertLive("fitBounds");
+        assertBounds(bounds);
+        const previous = this.getViewport();
+        this.#adapter?.fitBounds?.(bounds, options);
+        this.#commitViewport({ bbox: [...bounds] }, "controller");
+        this.#emit({ type: "viewport-move-end", viewport: this.getViewport(), previous, source: "controller" });
+        this.#queueIdle("controller");
+    }
+    onViewportMove(listener) {
+        return this.on("viewport-move", listener);
+    }
+    onViewportMoveEnd(listener) {
+        return this.on("viewport-move-end", listener);
+    }
+    onIdle(listener) {
+        return this.on("idle", listener);
+    }
+    getSelection(options = {}) {
+        this.#assertLive("getSelection");
+        const selection = this.context.state.selection;
+        if (!options.sourceId)
+            return cloneSelection(selection);
+        return cloneSelection(selection.filter((target) => isSourceQualifiedSelectionTarget(target) && target.sourceId === options.sourceId));
+    }
+    selectFeature(sourceOrTarget, idOrOptions, maybeOptions = {}) {
+        this.#assertLive("selectFeature");
+        const target = typeof sourceOrTarget === "object"
+            ? sourceOrTarget
+            : sourceFeatureSelectionTarget(sourceOrTarget, idOrOptions, {
+                sourceLayer: maybeOptions.sourceLayer,
+            });
+        const replace = typeof idOrOptions === "object" ? idOrOptions.replace : maybeOptions.replace;
+        this.selectFeatures([target], { replace: replace ?? true });
+    }
+    selectFeatures(targets, options = {}) {
+        this.#assertLive("selectFeatures");
+        if (targets.length === 0)
+            return;
+        this.context.dispatch({ kind: "select", ids: cloneSelection(targets), replace: options.replace ?? true });
+    }
+    clearSelection(targets) {
+        this.#assertLive("clearSelection");
+        this.context.dispatch({ kind: "deselect", ids: targets ? cloneSelection(targets) : undefined });
+    }
+    onSelectionChange(listener) {
+        return this.on("selection-change", listener);
+    }
+    getVisibility() {
+        this.#assertLive("getVisibility");
+        return cloneVisibility(this.#visibility);
+    }
+    setVisibility(update) {
+        this.#assertLive("setVisibility");
+        this.#applyVisibilityUpdate(normalizeVisibilityUpdate(update), "controller");
+    }
+    setLayerVisibility(layerOrUpdate, visible) {
+        this.#assertLive("setLayerVisibility");
+        if (typeof layerOrUpdate === "string") {
+            this.#applyVisibilityUpdate({
+                show: visible ? [{ kind: "layer", id: layerOrUpdate }] : [],
+                hide: visible ? [] : [{ kind: "layer", id: layerOrUpdate }],
+            }, "controller");
+            return;
+        }
+        this.#applyVisibilityUpdate(targetsFromChangeSet("layer", layerOrUpdate), "controller");
+    }
+    setLayerGroupVisibility(update) {
+        this.#assertLive("setLayerGroupVisibility");
+        this.#applyVisibilityUpdate(targetsFromChangeSet("layer-group", update), "controller");
+    }
+    setLegendItemVisibility(update) {
+        this.#assertLive("setLegendItemVisibility");
+        this.#applyVisibilityUpdate(targetsFromChangeSet("legend-item", update), "controller");
+    }
+    onVisibilityChange(listener) {
+        return this.on("visibility-change", listener);
+    }
+    getSource(sourceId) {
+        this.#assertLive("getSource");
+        return cloneStyleValue(this.#currentStyle()?.sources[sourceId]);
+    }
+    listSources() {
+        this.#assertLive("listSources");
+        return cloneStyleValue(this.#currentStyle()?.sources ?? {});
+    }
+    getLayer(layerId) {
+        this.#assertLive("getLayer");
+        return cloneStyleValue(this.#currentStyle()?.layers.find((layer) => layer.id === layerId));
+    }
+    listLayers() {
+        this.#assertLive("listLayers");
+        return cloneStyleValue(this.#currentStyle()?.layers ?? []);
+    }
+    addSource(sourceId, source) {
+        this.#assertLive("addSource");
+        this.#requireLayerSourceAdapter("addSource").addSource?.(sourceId, source);
+        this.#recordLayerSourceMutation({ action: "source-added", sourceId });
+    }
+    updateSource(sourceId, source) {
+        this.#assertLive("updateSource");
+        this.#requireLayerSourceAdapter("updateSource").updateSource?.(sourceId, source);
+        this.#recordLayerSourceMutation({ action: "source-updated", sourceId });
+    }
+    removeSource(sourceId) {
+        this.#assertLive("removeSource");
+        const removedLayerIds = [...(this.#requireLayerSourceAdapter("removeSource").removeSource?.(sourceId) ?? [])];
+        this.#recordLayerSourceMutation({ action: "source-removed", sourceId, removedLayerIds });
+        return removedLayerIds;
+    }
+    addLayer(layer, order) {
+        this.#assertLive("addLayer");
+        this.#requireLayerSourceAdapter("addLayer").addLayer?.(layer, order);
+        this.#recordLayerSourceMutation({ action: "layer-added", layerId: layer.id, sourceId: layer.source, order });
+    }
+    updateLayer(layerId, update) {
+        this.#assertLive("updateLayer");
+        this.#requireLayerSourceAdapter("updateLayer").updateLayer?.(layerId, update);
+        this.#recordLayerSourceMutation({ action: "layer-updated", layerId, sourceId: this.getLayer(layerId)?.source });
+    }
+    moveLayer(layerId, order) {
+        this.#assertLive("moveLayer");
+        this.#requireLayerSourceAdapter("moveLayer").moveLayer?.(layerId, order);
+        this.#recordLayerSourceMutation({
+            action: "layer-moved",
+            layerId,
+            sourceId: this.getLayer(layerId)?.source,
+            order,
+        });
+    }
+    removeLayer(layerId) {
+        this.#assertLive("removeLayer");
+        const sourceId = this.getLayer(layerId)?.source;
+        const removed = this.#requireLayerSourceAdapter("removeLayer").removeLayer?.(layerId) ?? false;
+        if (removed)
+            this.#recordLayerSourceMutation({ action: "layer-removed", layerId, sourceId });
+        return removed;
+    }
+    setLayerPaint(layerId, paint) {
+        this.#assertLive("setLayerPaint");
+        this.#requireLayerSourceAdapter("setLayerPaint").setLayerPaint?.(layerId, paint);
+        this.#recordLayerSourceMutation({ action: "layer-updated", layerId, sourceId: this.getLayer(layerId)?.source });
+    }
+    setLayerLayout(layerId, layout) {
+        this.#assertLive("setLayerLayout");
+        this.#requireLayerSourceAdapter("setLayerLayout").setLayerLayout?.(layerId, layout);
+        this.#recordLayerSourceMutation({ action: "layer-updated", layerId, sourceId: this.getLayer(layerId)?.source });
+    }
+    setLayerFilter(layerId, filter) {
+        this.#assertLive("setLayerFilter");
+        this.#requireLayerSourceAdapter("setLayerFilter").setLayerFilter?.(layerId, filter);
+        this.#recordLayerSourceMutation({ action: "layer-updated", layerId, sourceId: this.getLayer(layerId)?.source });
+    }
+    refreshSource(sourceId) {
+        this.#assertLive("refreshSource");
+        const refreshed = this.#requireLayerSourceAdapter("refreshSource").refreshSource?.(sourceId) ?? false;
+        this.#emitLayerSourceMutation({ action: "source-refreshed", sourceId });
+        return refreshed;
+    }
+    validateStyleExpression(value) {
+        this.#assertLive("validateStyleExpression");
+        return [...(this.#requireLayerSourceAdapter("validateStyleExpression").validateStyleExpression?.(value) ?? [])];
+    }
+    validateFilterExpression(filter, layerId) {
+        this.#assertLive("validateFilterExpression");
+        return [
+            ...(this.#requireLayerSourceAdapter("validateFilterExpression").validateFilterExpression?.(filter, layerId) ??
+                []),
+        ];
+    }
+    getPendingLayerSourceMutations() {
+        this.#assertLive("getPendingLayerSourceMutations");
+        return structuredClone(this.#layerSourceMutations);
+    }
+    hasPendingLayerSourceMutations() {
+        this.#assertLive("hasPendingLayerSourceMutations");
+        return this.#layerSourceMutations.length > 0;
+    }
+    async saveLayerSourceChanges(options = {}) {
+        this.#assertLive("saveLayerSourceChanges");
+        const payload = this.#layerSourcePersistencePayload(options);
+        const result = await this.#invokeLayerSourcePersistence("save", payload);
+        const conflict = result?.conflict ?? false;
+        if (!conflict) {
+            this.#layerSourceMutations = [];
+            this.#layerSourceVersion = result?.version ?? options.baseVersion ?? this.#layerSourceVersion;
+            this.#layerSourceConcurrencyToken =
+                result?.concurrencyToken ?? options.concurrencyToken ?? this.#layerSourceConcurrencyToken;
+        }
+        return persistenceOutcome(payload.mutations.length, Boolean(this.#layerSourcePersistence?.save), result);
+    }
+    async discardLayerSourceChanges(options = {}) {
+        this.#assertLive("discardLayerSourceChanges");
+        const payload = this.#layerSourcePersistencePayload(options);
+        const result = await this.#invokeLayerSourcePersistence("discard", payload);
+        if (!result?.conflict)
+            this.#layerSourceMutations = [];
+        return persistenceOutcome(payload.mutations.length, Boolean(this.#layerSourcePersistence?.discard), result);
+    }
+    onLayerSourceChange(listener) {
+        return this.on("layer-source-change", listener);
+    }
+    addOverlay(input) {
+        this.#assertLive("addOverlay");
+        const overlay = normalizeOverlay(input);
+        const action = this.#overlays.has(overlay.id) ? "updated" : "added";
+        if (action === "updated")
+            this.#adapter?.removeOverlay?.(overlay.id);
+        this.#overlays.set(overlay.id, overlay);
+        this.#adapter?.addOverlay?.(overlay);
+        this.#emit({
+            type: "overlay-change",
+            action,
+            overlay,
+            overlays: this.getOverlays(),
+            source: "controller",
+        });
+        return structuredClone(overlay);
+    }
+    removeOverlay(id) {
+        this.#assertLive("removeOverlay");
+        if (!this.#overlays.has(id))
+            return false;
+        this.#overlays.delete(id);
+        this.#adapter?.removeOverlay?.(id);
+        this.#emit({
+            type: "overlay-change",
+            action: "removed",
+            overlayId: id,
+            overlays: this.getOverlays(),
+            source: "controller",
+        });
+        return true;
+    }
+    clearOverlays() {
+        this.#assertLive("clearOverlays");
+        if (this.#overlays.size === 0)
+            return;
+        for (const id of this.#overlays.keys())
+            this.#adapter?.removeOverlay?.(id);
+        this.#overlays.clear();
+        this.#emit({ type: "overlay-change", action: "cleared", overlays: [], source: "controller" });
+    }
+    getOverlays() {
+        this.#assertLive("getOverlays");
+        return structuredClone([...this.#overlays.values()]);
+    }
+    addAnnotation(input) {
+        this.#assertLive("addAnnotation");
+        const annotation = normalizeAnnotation(input);
+        const action = this.#annotations.has(annotation.id) ? "updated" : "added";
+        if (action === "updated")
+            this.#adapter?.removeAnnotation?.(annotation.id);
+        this.#annotations.set(annotation.id, annotation);
+        this.#adapter?.addAnnotation?.(annotation);
+        this.#emit({
+            type: "annotation-change",
+            action,
+            annotation,
+            annotations: this.getAnnotations(),
+            source: "controller",
+        });
+        return structuredClone(annotation);
+    }
+    removeAnnotation(id) {
+        this.#assertLive("removeAnnotation");
+        if (!this.#annotations.has(id))
+            return false;
+        this.#annotations.delete(id);
+        this.#adapter?.removeAnnotation?.(id);
+        this.#emit({
+            type: "annotation-change",
+            action: "removed",
+            annotationId: id,
+            annotations: this.getAnnotations(),
+            source: "controller",
+        });
+        return true;
+    }
+    clearAnnotations() {
+        this.#assertLive("clearAnnotations");
+        if (this.#annotations.size === 0)
+            return;
+        for (const id of this.#annotations.keys())
+            this.#adapter?.removeAnnotation?.(id);
+        this.#annotations.clear();
+        this.#emit({ type: "annotation-change", action: "cleared", annotations: [], source: "controller" });
+    }
+    getAnnotations() {
+        this.#assertLive("getAnnotations");
+        return structuredClone([...this.#annotations.values()]);
+    }
+    snapshot() {
+        this.#assertLive("snapshot");
+        return {
+            version: HONUA_CONTROLLER_SNAPSHOT_VERSION,
+            viewport: this.getViewport(),
+            exploration: this.context.snapshot(),
+            visibility: this.getVisibility(),
+            overlays: this.getOverlays(),
+            annotations: this.getAnnotations(),
+        };
+    }
+    restore(snapshot) {
+        this.#assertLive("restore");
+        if (snapshot.version !== HONUA_CONTROLLER_SNAPSHOT_VERSION) {
+            throw new HonuaControllerError("invalid-snapshot", `HonuaController cannot restore snapshot version ${String(snapshot.version)}`);
+        }
+        this.setViewport(snapshot.viewport);
+        this.context.restore(snapshot.exploration);
+        this.#restoreVisibility(snapshot.visibility);
+        for (const id of this.#overlays.keys())
+            this.#adapter?.removeOverlay?.(id);
+        this.#overlays.clear();
+        for (const overlay of snapshot.overlays) {
+            const normalized = normalizeOverlay(overlay);
+            this.#overlays.set(normalized.id, normalized);
+            this.#adapter?.addOverlay?.(normalized);
+        }
+        this.#emit({
+            type: "overlay-change",
+            action: "restored",
+            overlays: this.getOverlays(),
+            source: "snapshot",
+        });
+        for (const id of this.#annotations.keys())
+            this.#adapter?.removeAnnotation?.(id);
+        this.#annotations.clear();
+        for (const annotation of snapshot.annotations) {
+            const normalized = normalizeAnnotation(annotation);
+            this.#annotations.set(normalized.id, normalized);
+            this.#adapter?.addAnnotation?.(normalized);
+        }
+        this.#emit({
+            type: "annotation-change",
+            action: "restored",
+            annotations: this.getAnnotations(),
+            source: "snapshot",
+        });
+    }
+    on(type, listener) {
+        this.#assertLive("on");
+        let listeners = this.#listeners.get(type);
+        if (!listeners) {
+            listeners = new Set();
+            this.#listeners.set(type, listeners);
+        }
+        const controllerListener = listener;
+        listeners.add(controllerListener);
+        return () => {
+            const set = this.#listeners.get(type);
+            if (!set)
+                return;
+            set.delete(controllerListener);
+            if (set.size === 0)
+                this.#listeners.delete(type);
+        };
+    }
+    dispose() {
+        if (this.#disposed)
+            return;
+        for (const unsubscribe of this.#subscriptions.splice(0))
+            unsubscribe();
+        for (const id of this.#overlays.keys())
+            this.#adapter?.removeOverlay?.(id);
+        for (const id of this.#annotations.keys())
+            this.#adapter?.removeAnnotation?.(id);
+        this.#overlays.clear();
+        this.#annotations.clear();
+        if (this.#disposeAdapter)
+            this.#adapter?.dispose?.();
+        if (this.#disposeRuntime)
+            this.#runtime?.dispose?.();
+        if (this.#ownsContext)
+            this.context.dispose();
+        this.#disposed = true;
+        this.#emit({ type: "disposed" });
+        this.#listeners.clear();
+    }
+    #currentStyle() {
+        return this.#adapter?.getStyle?.() ?? this.#runtime?.composedStyle ?? this.#runtime?.mapPackage.mapSpec;
+    }
+    #requireLayerSourceAdapter(operation) {
+        const adapter = this.#adapter;
+        if (!adapter || typeof adapter[operation] !== "function") {
+            throw new HonuaControllerError("invalid-layer-source", `HonuaController cannot ${String(operation)} without a layer/source adapter method`);
+        }
+        return adapter;
+    }
+    #recordLayerSourceMutation(input) {
+        this.#emitLayerSourceMutation(input, true);
+    }
+    #emitLayerSourceMutation(input, pending = false) {
+        const mutation = { ...input, timestamp: new Date().toISOString() };
+        if (pending)
+            this.#layerSourceMutations.push(mutation);
+        this.#emit({
+            type: "layer-source-change",
+            action: mutation.action,
+            sourceId: mutation.sourceId,
+            layerId: mutation.layerId,
+            removedLayerIds: mutation.removedLayerIds,
+            mutation,
+            pendingMutations: structuredClone(this.#layerSourceMutations),
+            source: "controller",
+        });
+    }
+    #layerSourcePersistencePayload(options) {
+        return {
+            mutations: structuredClone(this.#layerSourceMutations),
+            style: cloneStyleValue(this.#currentStyle()),
+            mapPackage: cloneStyleValue(this.#runtime?.mapPackage),
+            baseVersion: options.baseVersion ?? this.#layerSourceVersion,
+            concurrencyToken: options.concurrencyToken ?? this.#layerSourceConcurrencyToken,
+            metadata: options.metadata,
+        };
+    }
+    async #invokeLayerSourcePersistence(operation, payload) {
+        try {
+            return (await this.#layerSourcePersistence?.[operation]?.(payload)) ?? undefined;
+        }
+        catch (error) {
+            throw new HonuaControllerError("persistence-failed", `HonuaController ${operation}LayerSourceChanges persistence hook failed: ${errorMessage(error)}`);
+        }
+    }
+    #commitViewport(viewport, source, options = {}) {
+        const previous = this.#viewport;
+        this.#viewport = normalizeViewport({ ...this.#viewport, ...viewport });
+        const extent = viewportToExtent(this.#viewport);
+        if (extent) {
+            this.#suppressExtentEvent = true;
+            try {
+                this.context.dispatch({ kind: "set-extent", extent });
+            }
+            finally {
+                this.#suppressExtentEvent = false;
+            }
+        }
+        if (options.emitMove === false || viewportsEqual(previous, this.#viewport))
+            return;
+        this.#emit({ type: "viewport-move", viewport: this.getViewport(), previous, source });
+    }
+    #applyVisibilityUpdate(update, source) {
+        if (update.show.length === 0 && update.hide.length === 0)
+            return;
+        const previous = cloneVisibility(this.#visibility);
+        const next = cloneVisibility(this.#visibility);
+        const rendererChanges = new Map();
+        for (const target of update.hide)
+            applyVisibilityTarget(next, target, false, this.#layerGroups, this.#legendItemLayers, rendererChanges);
+        for (const target of update.show)
+            applyVisibilityTarget(next, target, true, this.#layerGroups, this.#legendItemLayers, rendererChanges);
+        if (visibilityEqual(previous, next))
+            return;
+        for (const [layerId, visible] of rendererChanges)
+            this.#adapter?.setLayerVisibility?.(layerId, visible);
+        this.#visibility = next;
+        this.#emit({
+            type: "visibility-change",
+            visibility: cloneVisibility(next),
+            previous,
+            show: update.show,
+            hide: update.hide,
+            source,
+        });
+    }
+    #restoreVisibility(visibility) {
+        const previous = cloneVisibility(this.#visibility);
+        const next = cloneVisibility(visibility);
+        if (visibilityEqual(previous, next))
+            return;
+        const layerIds = new Set([...Object.keys(previous.layers), ...Object.keys(next.layers)]);
+        for (const layerId of layerIds) {
+            const visible = next.layers[layerId] ?? true;
+            if ((previous.layers[layerId] ?? true) !== visible) {
+                this.#adapter?.setLayerVisibility?.(layerId, visible);
+            }
+        }
+        this.#visibility = next;
+        this.#emit({
+            type: "visibility-change",
+            visibility: cloneVisibility(next),
+            previous,
+            show: [],
+            hide: [],
+            source: "snapshot",
+        });
+    }
+    #queueIdle(source) {
+        queueMicrotask(() => {
+            if (this.#disposed)
+                return;
+            this.#emit({ type: "idle", snapshot: this.snapshot(), source });
+        });
+    }
+    #emit(event) {
+        const listeners = this.#listeners.get(event.type);
+        if (!listeners)
+            return;
+        for (const listener of [...listeners]) {
+            listener(event);
+        }
+    }
+    #assertLive(operation) {
+        if (this.#disposed) {
+            throw new HonuaControllerError("disposed", `HonuaController cannot ${operation} after dispose()`);
+        }
+    }
+}
+function resolveInternals(options) {
+    const generatedRuntime = options.runtime && isGeneratedAppRuntimeLike(options.runtime) ? options.runtime : undefined;
+    const runtime = options.runtime && isMapRuntimeLike(options.runtime)
+        ? options.runtime
+        : generatedRuntime?.mapRuntime && isMapRuntimeLike(generatedRuntime.mapRuntime)
+            ? generatedRuntime.mapRuntime
+            : undefined;
+    if (options.runtime && !generatedRuntime && !runtime) {
+        throw new HonuaControllerError("invalid-runtime", "HonuaController runtime must be a HonuaMapRuntime-like or generated-app-runtime-like object");
+    }
+    const context = options.explorationContext ?? generatedRuntime?.context;
+    const adapter = options.adapter ?? (runtime ? createMapRuntimeControllerAdapter(runtime) : undefined);
+    const initialViewport = options.initialViewport ??
+        adapter?.getViewport?.() ??
+        runtime?.mapPackage.initialView ??
+        extentToViewport(context?.state.extent);
+    if (context) {
+        const visibility = mergeVisibility(initialVisibilityFromRuntime(runtime, options.layerGroups, options.legendItemLayers), options.initialVisibility);
+        return {
+            context,
+            ownsContext: false,
+            runtime,
+            adapter,
+            disposeRuntime: options.disposeRuntime ?? false,
+            disposeAdapter: options.disposeAdapter ?? false,
+            initialViewport: normalizeViewport(initialViewport),
+            initialVisibility: visibility,
+            layerSourcePersistence: options.layerSourcePersistence,
+        };
+    }
+    const sourceIds = options.sourceIds ?? runtime?.mapPackage.sourceBindings.map((binding) => binding.sourceId) ?? [];
+    const datasetId = options.datasetId ?? runtime?.mapPackage.mapPackageId ?? "honua-controller";
+    const ownedContext = createExplorationContext({
+        datasetId,
+        sourceIds,
+        initialState: viewportToExtent(initialViewport) ? { extent: viewportToExtent(initialViewport) } : undefined,
+    });
+    const visibility = mergeVisibility(initialVisibilityFromRuntime(runtime, options.layerGroups, options.legendItemLayers), options.initialVisibility);
+    return {
+        context: ownedContext,
+        ownsContext: true,
+        runtime,
+        adapter,
+        disposeRuntime: options.disposeRuntime ?? false,
+        disposeAdapter: options.disposeAdapter ?? false,
+        initialViewport: normalizeViewport(initialViewport),
+        initialVisibility: visibility,
+        layerSourcePersistence: options.layerSourcePersistence,
+    };
+}
+function isControllerOptions(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const runtime = value;
+    return !isMapRuntimeLike(runtime) && !isGeneratedAppRuntimeLike(runtime);
+}
+function isGeneratedAppRuntimeLike(value) {
+    return typeof value === "object" && value !== null && "context" in value;
+}
+function isMapRuntimeLike(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "map" in value &&
+        "mapPackage" in value &&
+        "setViewState" in value &&
+        "setLayerVisibility" in value);
+}
+function createMapRuntimeControllerAdapter(runtime) {
+    const map = runtime.map;
+    const overlayLayers = new Map();
+    const annotationLayers = new Map();
+    const supportsTemporaryLayers = typeof map.addSource === "function" &&
+        typeof map.addLayer === "function" &&
+        typeof map.removeLayer === "function" &&
+        typeof map.removeSource === "function";
+    const adapter = {
+        id: `map-runtime:${runtime.mapPackage.mapPackageId}`,
+        getStyle() {
+            return runtime.composedStyle;
+        },
+        getViewport() {
+            return readMapViewport(map) ?? normalizeViewport(runtime.mapPackage.initialView ?? {});
+        },
+        setViewport(viewport, options) {
+            runtime.setViewState({
+                ...viewport,
+                ...(viewport.bbox ? { bbox: viewport.bbox } : {}),
+                animate: options?.animate,
+                padding: options?.padding,
+            });
+        },
+        fitBounds(bounds, options) {
+            runtime.setViewState({
+                bbox: bounds,
+                animate: options?.animate,
+                padding: options?.padding,
+                ...(options?.bearing !== undefined ? { bearing: options.bearing } : {}),
+                ...(options?.pitch !== undefined ? { pitch: options.pitch } : {}),
+            });
+        },
+        setLayerVisibility(layerId, visible) {
+            runtime.setLayerVisibility(layerId, visible);
+        },
+        addSource(sourceId, source) {
+            assertRuntimeCrud(runtime, "addSource");
+            runtime.addSource(sourceId, source);
+        },
+        updateSource(sourceId, source) {
+            assertRuntimeCrud(runtime, "updateSource");
+            runtime.updateSource(sourceId, source);
+        },
+        removeSource(sourceId) {
+            assertRuntimeCrud(runtime, "removeSource");
+            return runtime.removeSource(sourceId);
+        },
+        addLayer(layer, order) {
+            assertRuntimeCrud(runtime, "addLayer");
+            runtime.addLayer(layer, order);
+        },
+        updateLayer(layerId, update) {
+            assertRuntimeCrud(runtime, "updateLayer");
+            runtime.updateLayer(layerId, update);
+        },
+        moveLayer(layerId, order) {
+            assertRuntimeCrud(runtime, "moveLayer");
+            runtime.moveLayer(layerId, order);
+        },
+        removeLayer(layerId) {
+            assertRuntimeCrud(runtime, "removeLayer");
+            return runtime.removeLayer(layerId);
+        },
+        setLayerPaint(layerId, paint) {
+            assertRuntimeCrud(runtime, "setLayerPaint");
+            runtime.setLayerPaint(layerId, paint);
+        },
+        setLayerLayout(layerId, layout) {
+            assertRuntimeCrud(runtime, "setLayerLayout");
+            runtime.setLayerLayout(layerId, layout);
+        },
+        setLayerFilter(layerId, filter) {
+            assertRuntimeCrud(runtime, "setLayerFilter");
+            runtime.setLayerFilter(layerId, filter);
+        },
+        refreshSource(sourceId) {
+            assertRuntimeCrud(runtime, "refreshSource");
+            return runtime.refreshSource(sourceId);
+        },
+        validateStyleExpression(value) {
+            assertRuntimeCrud(runtime, "validateStyleExpression");
+            return runtime.validateStyleExpression(value);
+        },
+        validateFilterExpression(filter, layerId) {
+            assertRuntimeCrud(runtime, "validateFilterExpression");
+            return runtime.validateFilterExpression(filter, layerId);
+        },
+        onViewportMove(listener) {
+            return subscribeMapEvent(map, "move", () => listener(readMapViewport(map)));
+        },
+        onViewportMoveEnd(listener) {
+            return subscribeMapEvent(map, "moveend", () => listener(readMapViewport(map)));
+        },
+        onIdle(listener) {
+            return subscribeMapEvent(map, "idle", listener);
+        },
+    };
+    if (supportsTemporaryLayers) {
+        adapter.addOverlay = (overlay) => {
+            removeTemporaryMapItem(map, "overlay", overlay.id, overlayLayers);
+            const sourceId = temporarySourceId("overlay", overlay.id);
+            map.addSource?.(sourceId, { type: "geojson", data: overlayToGeoJson(overlay) });
+            const layers = overlayLayerSpecs(sourceId, overlay);
+            for (const layer of layers)
+                map.addLayer?.(layer);
+            overlayLayers.set(overlay.id, layers.map((layer) => String(layer.id)));
+        };
+        adapter.removeOverlay = (overlayId) => {
+            removeTemporaryMapItem(map, "overlay", overlayId, overlayLayers);
+        };
+        adapter.addAnnotation = (annotation) => {
+            removeTemporaryMapItem(map, "annotation", annotation.id, annotationLayers);
+            const geojson = annotationToGeoJson(annotation);
+            if (!geojson)
+                return;
+            const sourceId = temporarySourceId("annotation", annotation.id);
+            map.addSource?.(sourceId, { type: "geojson", data: geojson });
+            const layers = annotationLayerSpecs(sourceId, annotation);
+            for (const layer of layers)
+                map.addLayer?.(layer);
+            annotationLayers.set(annotation.id, layers.map((layer) => String(layer.id)));
+        };
+        adapter.removeAnnotation = (annotationId) => {
+            removeTemporaryMapItem(map, "annotation", annotationId, annotationLayers);
+        };
+    }
+    return adapter;
+}
+function readMapViewport(map) {
+    const viewport = {};
+    const bounds = map.getBounds?.();
+    if (bounds) {
+        viewport.bbox = [
+            Math.min(bounds.getWest(), bounds.getEast()),
+            Math.min(bounds.getSouth(), bounds.getNorth()),
+            Math.max(bounds.getWest(), bounds.getEast()),
+            Math.max(bounds.getSouth(), bounds.getNorth()),
+        ];
+    }
+    const center = map.getCenter?.();
+    if (Array.isArray(center)) {
+        viewport.center = [center[0], center[1]];
+    }
+    else if (center && "lng" in center) {
+        viewport.center = [center.lng, center.lat];
+    }
+    else if (center && "lon" in center) {
+        viewport.center = [center.lon, center.lat];
+    }
+    const zoom = map.getZoom?.();
+    if (zoom !== undefined)
+        viewport.zoom = zoom;
+    const pitch = map.getPitch?.();
+    if (pitch !== undefined)
+        viewport.pitch = pitch;
+    const bearing = map.getBearing?.();
+    if (bearing !== undefined)
+        viewport.bearing = bearing;
+    return Object.keys(viewport).length > 0 ? viewport : undefined;
+}
+function subscribeMapEvent(map, event, listener) {
+    map.on?.(event, listener);
+    return () => map.off?.(event, listener);
+}
+function assertRuntimeCrud(runtime, operation) {
+    if (typeof runtime[operation] !== "function") {
+        throw new HonuaControllerError("invalid-layer-source", `HonuaController runtime does not implement ${String(operation)}`);
+    }
+}
+function removeAdapterSubscription(subscription) {
+    if (typeof subscription === "function")
+        return subscription;
+    return () => subscription.remove();
+}
+function normalizeViewport(viewport) {
+    if (!viewport)
+        return {};
+    if (viewport.bbox)
+        assertBounds(viewport.bbox);
+    if (viewport.center)
+        assertCoordinate2d(viewport.center, "center");
+    for (const [key, value] of Object.entries({
+        zoom: viewport.zoom,
+        pitch: viewport.pitch,
+        bearing: viewport.bearing,
+    })) {
+        if (value !== undefined && !Number.isFinite(value)) {
+            throw new HonuaControllerError("invalid-viewport", `viewport.${key} must be a finite number`);
+        }
+    }
+    return structuredClone(viewport);
+}
+function assertBounds(bounds) {
+    if (bounds.length !== 4 || bounds.some((value) => !Number.isFinite(value))) {
+        throw new HonuaControllerError("invalid-viewport", "viewport bounds must be [west, south, east, north]");
+    }
+    if (bounds[0] > bounds[2] || bounds[1] > bounds[3]) {
+        throw new HonuaControllerError("invalid-viewport", "viewport bounds must be ordered west,south,east,north");
+    }
+}
+function assertCoordinate2d(coordinate, label) {
+    if (coordinate.length < 2 || !Number.isFinite(coordinate[0]) || !Number.isFinite(coordinate[1])) {
+        throw new HonuaControllerError("invalid-viewport", `${label} must contain finite longitude and latitude values`);
+    }
+}
+function viewportToExtent(viewport) {
+    if (!viewport?.bbox)
+        return undefined;
+    const [xmin, ymin, xmax, ymax] = viewport.bbox;
+    return {
+        xmin,
+        ymin,
+        xmax,
+        ymax,
+        spatialReference: viewport.crs === undefined || viewport.crs === "EPSG:4326" ? { wkid: 4326 } : { wkt: viewport.crs },
+    };
+}
+function extentToViewport(extent) {
+    if (!extent)
+        return {};
+    return {
+        bbox: [extent.xmin, extent.ymin, extent.xmax, extent.ymax],
+        crs: extent.spatialReference?.wkid !== undefined
+            ? `EPSG:${extent.spatialReference.wkid}`
+            : extent.spatialReference?.wkt,
+    };
+}
+function cloneViewport(viewport) {
+    return structuredClone(viewport);
+}
+function cloneStyleValue(value) {
+    return value === undefined ? value : structuredClone(value);
+}
+function persistenceOutcome(mutationCount, persisted, result) {
+    return {
+        mutationCount,
+        persisted,
+        conflict: result?.conflict ?? false,
+        version: result?.version,
+        concurrencyToken: result?.concurrencyToken,
+        detail: result?.detail,
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function viewportsEqual(a, b) {
+    return JSON.stringify(a ?? {}) === JSON.stringify(b ?? {});
+}
+function cloneSelection(selection) {
+    return structuredClone(selection);
+}
+function initialVisibilityFromRuntime(runtime, layerGroups, legendItemLayers) {
+    const layers = {};
+    const style = runtime?.composedStyle ?? runtime?.mapPackage.mapSpec;
+    for (const layer of style?.layers ?? []) {
+        layers[layer.id] = (layer.layout?.visibility ?? "visible") !== "none";
+    }
+    const layerGroupVisibility = {};
+    for (const [groupId, layerIds] of Object.entries(layerGroups ?? {})) {
+        layerGroupVisibility[groupId] = layerIds.every((layerId) => layers[layerId] ?? true);
+    }
+    const legendItems = {};
+    for (const entry of runtime?.getLegend?.() ?? []) {
+        legendItems[entry.id] = true;
+    }
+    for (const itemId of Object.keys(legendItemLayers ?? {})) {
+        legendItems[itemId] = legendItems[itemId] ?? true;
+    }
+    return { layers, layerGroups: layerGroupVisibility, legendItems };
+}
+function mergeVisibility(base, override) {
+    return {
+        layers: { ...base.layers, ...(override?.layers ?? {}) },
+        layerGroups: { ...base.layerGroups, ...(override?.layerGroups ?? {}) },
+        legendItems: { ...base.legendItems, ...(override?.legendItems ?? {}) },
+    };
+}
+function cloneVisibility(visibility) {
+    return structuredClone(visibility);
+}
+function visibilityEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+function targetsFromChangeSet(kind, update) {
+    return {
+        show: (update.show ?? []).map((id) => ({ kind, id })),
+        hide: (update.hide ?? []).map((id) => ({ kind, id })),
+    };
+}
+function normalizeVisibilityUpdate(update) {
+    return {
+        show: (update.show ?? []).map((target) => normalizeVisibilityTarget(target)),
+        hide: (update.hide ?? []).map((target) => normalizeVisibilityTarget(target)),
+    };
+}
+function normalizeVisibilityTarget(target) {
+    return typeof target === "string" ? { kind: "layer", id: target } : { kind: target.kind, id: target.id };
+}
+function applyVisibilityTarget(visibility, target, visible, layerGroups, legendItemLayers, rendererChanges) {
+    const layers = { ...visibility.layers };
+    const layerGroupState = { ...visibility.layerGroups };
+    const legendItemState = { ...visibility.legendItems };
+    switch (target.kind) {
+        case "layer":
+            layers[target.id] = visible;
+            rendererChanges.set(target.id, visible);
+            break;
+        case "layer-group":
+            layerGroupState[target.id] = visible;
+            for (const layerId of layerGroups[target.id] ?? []) {
+                layers[layerId] = visible;
+                rendererChanges.set(layerId, visible);
+            }
+            break;
+        case "legend-item":
+            legendItemState[target.id] = visible;
+            for (const layerId of legendItemLayers[target.id] ?? []) {
+                layers[layerId] = visible;
+                rendererChanges.set(layerId, visible);
+            }
+            break;
+    }
+    visibility.layers = layers;
+    visibility.layerGroups = layerGroupState;
+    visibility.legendItems = legendItemState;
+}
+function normalizeOverlay(input) {
+    const id = input.id?.trim() || `overlay-${++generatedOverlayId}`;
+    if (!id)
+        throw new HonuaControllerError("invalid-overlay", "overlay.id must not be empty");
+    switch (input.kind) {
+        case "geojson":
+            return structuredClone({ ...input, id });
+        case "point":
+            assertCoordinate(input.coordinate, "overlay.coordinate", "invalid-overlay");
+            return structuredClone({ ...input, id });
+        case "line":
+            if (input.coordinates.length < 2) {
+                throw new HonuaControllerError("invalid-overlay", "line overlay requires at least two coordinates");
+            }
+            for (const coordinate of input.coordinates)
+                assertCoordinate(coordinate, "overlay.coordinates", "invalid-overlay");
+            return structuredClone({ ...input, id });
+        case "polygon":
+            if (input.rings.length === 0 || input.rings[0].length < 4) {
+                throw new HonuaControllerError("invalid-overlay", "polygon overlay requires at least one closed ring");
+            }
+            for (const ring of input.rings) {
+                for (const coordinate of ring)
+                    assertCoordinate(coordinate, "overlay.rings", "invalid-overlay");
+            }
+            return structuredClone({ ...input, id });
+    }
+}
+function normalizeAnnotation(input) {
+    const id = input.id?.trim() || `annotation-${++generatedAnnotationId}`;
+    if (!id)
+        throw new HonuaControllerError("invalid-annotation", "annotation.id must not be empty");
+    if (!input.text.trim())
+        throw new HonuaControllerError("invalid-annotation", "annotation.text must not be empty");
+    if ("coordinate" in input && input.coordinate) {
+        assertCoordinate(input.coordinate, "annotation.coordinate", "invalid-annotation");
+    }
+    return structuredClone({ ...input, id });
+}
+function assertCoordinate(coordinate, label, code) {
+    if (coordinate.length < 2 || coordinate.length > 3 || coordinate.some((value) => !Number.isFinite(value))) {
+        throw new HonuaControllerError(code, `${label} must contain two or three finite numeric values`);
+    }
+}
+function temporarySourceId(kind, id) {
+    return `honua-controller-${kind}-${safeMapId(id)}`;
+}
+function safeMapId(id) {
+    return id.replace(/[^A-Za-z0-9_-]+/g, "-");
+}
+function removeTemporaryMapItem(map, kind, id, layersById) {
+    for (const layerId of [...(layersById.get(id) ?? [])].reverse())
+        map.removeLayer?.(layerId);
+    layersById.delete(id);
+    map.removeSource?.(temporarySourceId(kind, id));
+}
+function overlayToGeoJson(overlay) {
+    switch (overlay.kind) {
+        case "geojson":
+            return overlay.data;
+        case "point":
+            return {
+                type: "Feature",
+                id: overlay.id,
+                properties: overlay.properties ?? {},
+                geometry: { type: "Point", coordinates: overlay.coordinate },
+            };
+        case "line":
+            return {
+                type: "Feature",
+                id: overlay.id,
+                properties: overlay.properties ?? {},
+                geometry: { type: "LineString", coordinates: overlay.coordinates },
+            };
+        case "polygon":
+            return {
+                type: "Feature",
+                id: overlay.id,
+                properties: overlay.properties ?? {},
+                geometry: { type: "Polygon", coordinates: overlay.rings },
+            };
+    }
+}
+function annotationToGeoJson(annotation) {
+    if (!annotation.coordinate)
+        return undefined;
+    return {
+        type: "Feature",
+        id: annotation.id,
+        properties: { ...(annotation.properties ?? {}), text: annotation.text, kind: annotation.kind },
+        geometry: { type: "Point", coordinates: annotation.coordinate },
+    };
+}
+function overlayLayerSpecs(sourceId, overlay) {
+    const id = temporarySourceId("overlay", overlay.id);
+    const style = overlay.style ?? {};
+    const color = style.color ?? "#2563eb";
+    const pointLayer = {
+        id: `${id}-point`,
+        type: "circle",
+        source: sourceId,
+        filter: ["==", ["geometry-type"], "Point"],
+        paint: {
+            "circle-color": style.pointColor ?? color,
+            "circle-radius": style.pointRadius ?? 6,
+            "circle-opacity": style.opacity ?? 0.9,
+        },
+    };
+    const lineLayer = {
+        id: `${id}-line`,
+        type: "line",
+        source: sourceId,
+        filter: ["in", ["geometry-type"], "LineString", "Polygon"],
+        paint: {
+            "line-color": style.lineColor ?? color,
+            "line-width": style.lineWidth ?? 2,
+            "line-opacity": style.opacity ?? 0.95,
+        },
+    };
+    const fillLayer = {
+        id: `${id}-fill`,
+        type: "fill",
+        source: sourceId,
+        filter: ["==", ["geometry-type"], "Polygon"],
+        paint: {
+            "fill-color": style.fillColor ?? color,
+            "fill-opacity": style.fillOpacity ?? 0.18,
+        },
+    };
+    if (overlay.kind === "point")
+        return [pointLayer];
+    if (overlay.kind === "line")
+        return [lineLayer];
+    if (overlay.kind === "polygon")
+        return [fillLayer, lineLayer];
+    return [fillLayer, lineLayer, pointLayer];
+}
+function annotationLayerSpecs(sourceId, annotation) {
+    const id = temporarySourceId("annotation", annotation.id);
+    const style = annotation.style ?? {};
+    return [
+        {
+            id: `${id}-text`,
+            type: "symbol",
+            source: sourceId,
+            layout: {
+                "text-field": ["get", "text"],
+                "text-size": style.size ?? 13,
+                "text-anchor": style.anchor ?? "top",
+            },
+            paint: {
+                "text-color": style.color ?? "#111827",
+                "text-halo-color": style.haloColor ?? "#ffffff",
+                "text-halo-width": style.haloWidth ?? 1,
+            },
+        },
+    ];
+}