@honua/app-platform 0.0.20-alpha.0

package/generated-app/runtime.js

@@ -0,0 +1,1196 @@
+/**
+ * Framework-neutral generated-app preview runtime for the operations
+ * dashboard proof profile.
+ *
+ * The runtime composes the existing MapPackage loader, ExplorationContext,
+ * and interaction bindings into reusable widget models. Hosts own DOM,
+ * framework, and MapLibre construction; this module owns manifest binding,
+ * linked state, feature filtering, and structured preview errors.
+ *
+ * @module
+ */
+import { createExplorationContext, isSourceQualifiedSelectionTarget, selectLinkedViewQueryProjection, sourceFeatureSelectionTarget, } from "../exploration/index.js";
+import { bindChartToExploration, bindFilterControlsToExploration, bindTableSelectionToExploration, syncFeatureStateSelection, syncMapLayerFilterToExploration, } from "../interactions/index.js";
+import { loadMapPackage, } from "../runtime/index.js";
+import { HonuaGeneratedAppError, toGeneratedAppDiagnostic } from "./errors.js";
+import { HONUA_GENERATED_APP_DEFAULT_PREVIEW_LIMIT, HONUA_GENERATED_APP_MAX_PREVIEW_LIMIT, assertGeneratedAppManifest, clampGeneratedAppManifest, clampGeneratedAppPreviewLimit, projectAppPackageToGeneratedAppManifest, } from "./projection.js";
+export async function loadGeneratedAppRuntime(manifest, options) {
+    assertGeneratedAppManifest(manifest);
+    manifest = clampGeneratedAppManifest(manifest);
+    assertOperationsDashboardWidgets(manifest);
+    const sourceId = manifest.data.sourceId;
+    const mapWidget = findWidget(manifest, "map");
+    const mapPackage = manifest.mapPackage ?? options.mapPackage;
+    assertMapPackageMatchesManifest(manifest, mapPackage);
+    let mapRuntime;
+    let disposeMap;
+    if (mapWidget) {
+        if (!mapPackage) {
+            throw new HonuaGeneratedAppError("missing-map-package", "generated-app map widget requires a MapPackage", {
+                stage: "load",
+                detail: { appId: manifest.appId, widgetId: mapWidget.id, path: "GeneratedAppManifest.mapPackage" },
+            });
+        }
+        if (!options.mapFactory) {
+            throw new HonuaGeneratedAppError("missing-binding", "generated-app map widget requires options.mapFactory", {
+                stage: "load",
+                detail: { appId: manifest.appId, widgetId: mapWidget.id, path: "HonuaGeneratedAppLoadOptions.mapFactory" },
+            });
+        }
+        if (!options.mapLoadOptions) {
+            throw new HonuaGeneratedAppError("missing-binding", "generated-app map widget requires options.mapLoadOptions", {
+                stage: "load",
+                detail: { appId: manifest.appId, widgetId: mapWidget.id, path: "HonuaGeneratedAppLoadOptions.mapLoadOptions" },
+            });
+        }
+        try {
+            const factoryResult = await options.mapFactory(mapWidget, manifest);
+            disposeMap = factoryResult.dispose;
+            mapRuntime = await loadMapPackage(mapPackage, factoryResult.map, {
+                ...options.mapLoadOptions,
+                applyInitialView: options.mapLoadOptions.applyInitialView ?? true,
+            });
+        }
+        catch (cause) {
+            if (mapRuntime)
+                mapRuntime.dispose();
+            disposeMap?.();
+            throw new HonuaGeneratedAppError("map-load-failed", "generated-app map widget failed to load", {
+                stage: "load",
+                detail: { appId: manifest.appId, widgetId: mapWidget.id, widgetKind: "map" },
+                cause,
+            });
+        }
+    }
+    const sourceIds = unique([sourceId, ...(mapPackage?.sourceBindings.map((binding) => binding.sourceId) ?? [])]);
+    const context = createExplorationContext({
+        datasetId: manifest.appId,
+        sourceIds,
+        initialState: manifest.initialState,
+        preset: manifest.linkedViewPreset ?? "globalLinked",
+    });
+    const handles = [];
+    const table = {};
+    const chart = {};
+    const filter = {};
+    let mapView;
+    for (const widget of manifest.layout.widgets) {
+        switch (widget.kind) {
+            case "map": {
+                mapView = context.connectView({ id: widget.id, role: "map" });
+                const layerId = mapLayerIdForWidget(widget, manifest);
+                if (mapRuntime && layerId && mapRuntime.map.setFilter) {
+                    const setFilter = mapRuntime.map.setFilter.bind(mapRuntime.map);
+                    handles.push(syncMapLayerFilterToExploration({ setFilter }, mapView, {
+                        layerId,
+                        sourceId,
+                        translate: (projection) => compileMapLibreFilters(projection.filters, sourceId),
+                    }));
+                    handles.push(syncFeatureStateSelection(mapRuntime.map, mapView, {
+                        source: sourceId,
+                        sourceLayer: widget.sourceLayer,
+                        includeRawIds: false,
+                    }));
+                }
+                break;
+            }
+            case "table":
+            case "list": {
+                const view = context.connectView({ id: widget.id, role: "grid" });
+                table[widget.id] = bindTableSelectionToExploration(view);
+                break;
+            }
+            case "chart": {
+                const view = context.connectView({ id: widget.id, role: "chart" });
+                const binding = bindChartToExploration(view);
+                const groupBy = chartCategoryField(widget);
+                if (groupBy) {
+                    binding.setGrouping([groupBy]);
+                    binding.setAggregation({ groupBy: [groupBy], metrics: [widget.metric ?? { fn: "count", field: "*" }] });
+                }
+                chart[widget.id] = binding;
+                break;
+            }
+            case "filter": {
+                const view = context.connectView({ id: widget.id, role: "filter" });
+                filter[widget.id] = bindFilterControlsToExploration(view);
+                break;
+            }
+            case "count":
+                break;
+        }
+        options.onEvent?.({ type: "widget-bound", appId: manifest.appId, widgetId: widget.id, widgetKind: widget.kind });
+    }
+    const runtime = new HonuaGeneratedAppRuntime({
+        manifest,
+        context,
+        mapRuntime,
+        disposeMap,
+        bindings: { mapView, table, chart, filter },
+        handles,
+        initialFeatures: options.initialFeatures,
+        featureLoader: options.featureLoader,
+        widgetSource: options.widgetSource,
+        onEvent: options.onEvent,
+    });
+    try {
+        await runtime.refresh();
+    }
+    catch (error) {
+        runtime.dispose();
+        throw error;
+    }
+    options.onEvent?.({ type: "loaded", appId: manifest.appId });
+    return runtime;
+}
+export async function previewGeneratedApp(input, options) {
+    let manifest = input.manifest;
+    try {
+        if (!manifest && input.appPackage) {
+            manifest = projectAppPackageToGeneratedAppManifest(input.appPackage, {
+                mapPackage: input.mapPackage ?? options.mapPackage,
+            });
+        }
+        if (!manifest) {
+            throw new HonuaGeneratedAppError("missing-manifest", "previewGeneratedApp requires manifest or appPackage", {
+                stage: "projection",
+                detail: { path: "HonuaGeneratedAppPreviewInput.manifest" },
+            });
+        }
+        const runtime = await loadGeneratedAppRuntime(manifest, {
+            ...options,
+            mapPackage: input.mapPackage ?? options.mapPackage,
+        });
+        return {
+            status: "ready",
+            manifest,
+            runtime,
+            model: runtime.render(),
+            errors: [],
+        };
+    }
+    catch (error) {
+        const diagnostic = toGeneratedAppDiagnostic(error);
+        if (error instanceof HonuaGeneratedAppError)
+            options.onEvent?.({ type: "error", appId: manifest?.appId, error });
+        return {
+            status: "error",
+            ...(manifest ? { manifest } : {}),
+            errors: [diagnostic],
+        };
+    }
+}
+export class HonuaGeneratedAppRuntime {
+    manifest;
+    context;
+    mapRuntime;
+    #disposeMap;
+    #bindings;
+    #handles;
+    #initialFeatures;
+    #featureLoader;
+    #widgetSource;
+    #listeners = new Set();
+    #records = [];
+    #widgetModels;
+    #disposed = false;
+    constructor(internals) {
+        this.manifest = internals.manifest;
+        this.context = internals.context;
+        this.mapRuntime = internals.mapRuntime;
+        this.#disposeMap = internals.disposeMap;
+        this.#bindings = internals.bindings;
+        this.#handles = internals.handles;
+        this.#initialFeatures = internals.initialFeatures;
+        this.#featureLoader = internals.featureLoader;
+        this.#widgetSource = internals.widgetSource;
+        if (internals.onEvent)
+            this.#listeners.add(internals.onEvent);
+    }
+    on(listener) {
+        this.#listeners.add(listener);
+        return {
+            remove: () => {
+                this.#listeners.delete(listener);
+            },
+        };
+    }
+    async refresh() {
+        this.#assertLive("refresh");
+        try {
+            this.#records = await this.#loadFeatureRecords();
+            this.#widgetModels = await this.#loadWidgetSourceModels();
+            return this.render();
+        }
+        catch (cause) {
+            const error = new HonuaGeneratedAppError("data-load-failed", "generated-app feature data failed to load", {
+                stage: "load",
+                detail: { appId: this.manifest.appId, sourceId: this.manifest.data.sourceId },
+                cause,
+            });
+            this.#emit({ type: "error", appId: this.manifest.appId, error });
+            throw error;
+        }
+    }
+    render() {
+        this.#assertLive("render");
+        const sourceId = this.manifest.data.sourceId;
+        const projection = selectLinkedViewQueryProjection(this.context.state, { sourceId });
+        const filtered = applyProjection(this.#records, projection.filters, projection.selection, sourceId);
+        const paged = applySortAndPagination(filtered, this.context.state.sort, this.context.state.page);
+        const widgetModels = this.#widgetModels?.projectionKey === stableWidgetProjectionKey(projection) ? this.#widgetModels : undefined;
+        const widgets = this.manifest.layout.widgets.map((widget) => this.#renderWidget(widget, paged, filtered, widgetModels));
+        const model = {
+            status: "ready",
+            appId: this.manifest.appId,
+            ...(this.manifest.title ? { title: this.manifest.title } : {}),
+            sourceId,
+            visibleCount: filtered.length,
+            totalCount: this.#records.length,
+            widgets,
+            snapshot: this.context.snapshot(),
+        };
+        this.#emit({ type: "rendered", appId: this.manifest.appId, visibleCount: filtered.length });
+        return model;
+    }
+    setFilter(widgetId, value) {
+        this.#assertLive("setFilter");
+        const widget = this.#requireWidget(widgetId, "filter");
+        const binding = this.#bindings.filter[widgetId];
+        if (!binding) {
+            throw missingWidgetBinding(this.manifest.appId, widgetId, "filter");
+        }
+        if (value === undefined) {
+            binding.clearFilter(widget.id);
+        }
+        else {
+            binding.setFilter(widget.id, {
+                field: widget.field,
+                operator: "=",
+                value,
+                appliesTo: [widget.sourceId ?? this.manifest.data.sourceId],
+            });
+        }
+        return this.render();
+    }
+    selectChartBucket(widgetId, value) {
+        this.#assertLive("selectChartBucket");
+        const widget = this.#requireWidget(widgetId, "chart");
+        const binding = this.#bindings.chart[widgetId];
+        if (!binding) {
+            throw missingWidgetBinding(this.manifest.appId, widgetId, "chart");
+        }
+        const sourceId = widget.sourceId ?? this.manifest.data.sourceId;
+        const groupBy = chartCategoryField(widget);
+        if (!groupBy) {
+            throw missingWidgetBinding(this.manifest.appId, widgetId, "chart");
+        }
+        binding.setGrouping([groupBy]);
+        binding.setAggregation({ groupBy: [groupBy], metrics: [widget.metric ?? { fn: "count", field: "*" }] });
+        for (const [id, clause] of Object.entries(this.context.state.filters)) {
+            if (id !== widget.id && clause.field === groupBy) {
+                this.context.dispatch({ kind: "clear-filter", id, viewId: widget.id });
+            }
+        }
+        if (value === undefined) {
+            this.context.dispatch({ kind: "clear-filter", id: widget.id, viewId: widget.id });
+        }
+        else {
+            binding.selectBucket({
+                filters: {
+                    [widget.id]: {
+                        field: groupBy,
+                        operator: "=",
+                        value,
+                        appliesTo: [sourceId],
+                    },
+                },
+            });
+        }
+        return this.render();
+    }
+    selectRecord(widgetId, id, options = {}) {
+        this.#assertLive("selectRecord");
+        const widget = this.#requireWidget(widgetId, ["table", "list"]);
+        const binding = this.#bindings.table[widgetId];
+        if (!binding) {
+            throw missingWidgetBinding(this.manifest.appId, widgetId, "table");
+        }
+        binding.select([sourceFeatureSelectionTarget(this.#recordSourceIdForSelection(widget, id), id)], {
+            replace: options.replace ?? true,
+        });
+        return this.render();
+    }
+    snapshot() {
+        this.#assertLive("snapshot");
+        return this.context.snapshot();
+    }
+    restore(snapshot) {
+        this.#assertLive("restore");
+        this.context.restore(snapshot);
+        return this.render();
+    }
+    dispose() {
+        if (this.#disposed)
+            return;
+        for (const handle of this.#handles)
+            handle.remove();
+        this.mapRuntime?.dispose();
+        this.#disposeMap?.();
+        this.context.dispose();
+        this.#disposed = true;
+        this.#emit({ type: "disposed", appId: this.manifest.appId });
+        this.#listeners.clear();
+    }
+    async #loadFeatureRecords() {
+        const sourceId = this.manifest.data.sourceId;
+        const projection = selectLinkedViewQueryProjection(this.context.state, { sourceId });
+        const raw = this.#initialFeatures ??
+            (this.#featureLoader
+                ? await this.#featureLoader({ manifest: this.manifest, sourceId, projection, mapRuntime: this.mapRuntime })
+                : await loadFeaturesFromMapRuntime(this.manifest, this.mapRuntime, projection));
+        return raw.map((feature, index) => normalizeFeatureRecord(feature, sourceId, this.#primaryKey(), index));
+    }
+    async #loadWidgetSourceModels() {
+        if (!this.#widgetSource)
+            return undefined;
+        const sourceId = this.manifest.data.sourceId;
+        const projection = selectLinkedViewQueryProjection(this.context.state, { sourceId });
+        const count = {};
+        const categories = {};
+        const histogram = {};
+        const timeSeries = {};
+        await runWithConcurrency(this.manifest.layout.widgets.map((widget) => async () => {
+            switch (widget.kind) {
+                case "count":
+                    count[widget.id] = await this.#widgetSource.count({ projection });
+                    break;
+                case "chart": {
+                    const chartKind = generatedChartKind(widget);
+                    if (chartKind === "histogram") {
+                        histogram[widget.id] = await this.#widgetSource.histogram({
+                            projection,
+                            field: chartMeasureField(widget),
+                            bins: widget.bins,
+                            min: widget.min,
+                            max: widget.max,
+                        });
+                    }
+                    else if (chartKind === "time-series") {
+                        timeSeries[widget.id] = await this.#widgetSource.timeSeries({
+                            projection,
+                            field: chartMeasureField(widget),
+                            interval: widget.interval,
+                            metric: widget.metric,
+                            start: widget.start,
+                            end: widget.end,
+                            fillMissing: widget.fillMissing,
+                        });
+                    }
+                    else {
+                        const groupBy = chartCategoryField(widget);
+                        if (groupBy) {
+                            categories[widget.id] = await this.#widgetSource.categories({
+                                projection,
+                                field: groupBy,
+                                metric: widget.metric,
+                            });
+                        }
+                    }
+                    break;
+                }
+                case "filter":
+                    categories[widget.id] = await this.#widgetSource.categories({
+                        projection,
+                        field: widget.field,
+                        limit: clampInteger(Math.max(widget.options?.length ?? 0, 25), 1, HONUA_GENERATED_APP_MAX_PREVIEW_LIMIT),
+                    });
+                    break;
+                case "map":
+                case "table":
+                case "list":
+                    break;
+            }
+        }), 4);
+        return { projectionKey: stableWidgetProjectionKey(projection), count, categories, histogram, timeSeries };
+    }
+    #renderWidget(widget, pagedRecords, filteredRecords, widgetModels) {
+        const sourceId = widget.sourceId ?? this.manifest.data.sourceId;
+        switch (widget.kind) {
+            case "map":
+                return {
+                    id: widget.id,
+                    kind: "map",
+                    ...(widget.title ? { title: widget.title } : {}),
+                    loaded: Boolean(this.mapRuntime),
+                    mapPackageId: this.mapRuntime?.mapPackage.mapPackageId ?? this.manifest.mapPackageId,
+                    layerId: mapLayerIdForWidget(widget, this.manifest),
+                    legend: widget.showLegend === false ? [] : (this.mapRuntime?.getLegend() ?? []),
+                    searchFields: widget.showSearch === false ? [] : (this.manifest.bindings?.searchFields ?? []),
+                };
+            case "table":
+            case "list": {
+                const fields = widget.fields ?? this.manifest.bindings?.tableFields ?? inferFields(pagedRecords);
+                return {
+                    id: widget.id,
+                    kind: widget.kind,
+                    ...(widget.title ? { title: widget.title } : {}),
+                    sourceId,
+                    fields,
+                    rows: pagedRecords.map((record) => this.#rowModel(record, fields, widget)),
+                };
+            }
+            case "count":
+                return {
+                    id: widget.id,
+                    kind: "count",
+                    ...(widget.title ? { title: widget.title } : {}),
+                    label: widget.label ?? widget.title ?? "Records",
+                    value: widgetModels?.count[widget.id]?.value ?? filteredRecords.length,
+                };
+            case "chart":
+                return chartModel(widget, filteredRecords, sourceId, this.context.state.filters, widgetModels);
+            case "filter":
+                return {
+                    id: widget.id,
+                    kind: "filter",
+                    ...(widget.title ? { title: widget.title } : {}),
+                    sourceId,
+                    field: widget.field,
+                    options: widgetModels?.categories[widget.id] !== undefined
+                        ? filterOptionsFromWidgetSource(widgetModels.categories[widget.id], widget, this.context.state.filters)
+                        : filterOptions(this.#records, this.context.state.filters, widget, sourceId),
+                };
+        }
+    }
+    #rowModel(record, fields, widget) {
+        const titleField = widget.titleField ?? this.manifest.bindings?.titleField ?? this.#primaryKey();
+        const subtitleField = widget.subtitleField ?? this.manifest.bindings?.subtitleField;
+        const sourceId = record.sourceId ?? widget.sourceId ?? this.manifest.data.sourceId;
+        return {
+            id: record.id,
+            sourceId,
+            title: stringValue(record.attributes[titleField] ?? record.id),
+            ...(subtitleField ? { subtitle: stringValue(record.attributes[subtitleField] ?? "") } : {}),
+            selected: selectionContains(this.context.state.selection, record, sourceId),
+            values: Object.fromEntries(fields.map((field) => [field, record.attributes[field]])),
+        };
+    }
+    #recordSourceIdForSelection(widget, id) {
+        const widgetSourceId = widget.sourceId ?? this.manifest.data.sourceId;
+        const exactRecord = this.#records.find((record) => record.id === id && (record.sourceId ?? widgetSourceId) === widgetSourceId);
+        if (exactRecord)
+            return exactRecord.sourceId ?? widgetSourceId;
+        const matchingRecords = this.#records.filter((record) => record.id === id);
+        if (matchingRecords.length === 1)
+            return matchingRecords[0].sourceId ?? widgetSourceId;
+        return widgetSourceId;
+    }
+    #primaryKey() {
+        return this.manifest.bindings?.primaryKey ?? "OBJECTID";
+    }
+    #requireWidget(widgetId, expected) {
+        const widget = this.manifest.layout.widgets.find((entry) => entry.id === widgetId);
+        const expectedKinds = Array.isArray(expected) ? expected : [expected];
+        if (!widget || !expectedKinds.includes(widget.kind)) {
+            throw new HonuaGeneratedAppError("missing-widget", `generated-app widget "${widgetId}" is not available`, {
+                stage: "interaction",
+                detail: { appId: this.manifest.appId, widgetId, expected: expectedKinds, received: widget?.kind },
+            });
+        }
+        return widget;
+    }
+    #assertLive(operation) {
+        if (this.#disposed) {
+            throw new HonuaGeneratedAppError("disposed", `generated-app runtime cannot ${operation} after dispose()`, {
+                stage: "dispose",
+                detail: { appId: this.manifest.appId },
+            });
+        }
+    }
+    #emit(event) {
+        for (const listener of this.#listeners)
+            listener(event);
+    }
+}
+async function loadFeaturesFromMapRuntime(manifest, mapRuntime, projection) {
+    const source = mapRuntime?.dataset.source(manifest.data.sourceId);
+    if (!source) {
+        throw new HonuaGeneratedAppError("missing-binding", "generated-app source is not available from the MapPackage", {
+            stage: "load",
+            detail: {
+                appId: manifest.appId,
+                sourceId: manifest.data.sourceId,
+                path: "HonuaMapRuntime.dataset.source",
+            },
+        });
+    }
+    const previewLimit = clampGeneratedAppPreviewLimit(projection.pagination.limit ?? manifest.data.previewLimit ?? HONUA_GENERATED_APP_DEFAULT_PREVIEW_LIMIT);
+    const query = {
+        returnGeometry: true,
+        outFields: generatedAppQueryFields(manifest),
+        orderBy: projection.orderBy,
+        pagination: { ...projection.pagination, limit: previewLimit ?? HONUA_GENERATED_APP_DEFAULT_PREVIEW_LIMIT },
+    };
+    const result = await source.query(query);
+    return result.features.map((feature) => ({
+        attributes: feature.attributes,
+        geometry: feature.geometry,
+    }));
+}
+function assertOperationsDashboardWidgets(manifest) {
+    const supported = new Set(["map", "table", "list", "count", "chart", "filter"]);
+    for (const widget of manifest.layout.widgets) {
+        if (!supported.has(widget.kind)) {
+            throw new HonuaGeneratedAppError("unsupported-widget", `unsupported generated-app widget "${widget.kind}"`, {
+                stage: "manifest",
+                detail: { appId: manifest.appId, widgetId: widget.id, widgetKind: widget.kind },
+            });
+        }
+    }
+    const requiredKinds = ["map", "count", "chart", "filter"];
+    for (const kind of requiredKinds) {
+        if (!manifest.layout.widgets.some((widget) => widget.kind === kind)) {
+            throw new HonuaGeneratedAppError("missing-widget", `operations dashboard manifest is missing ${kind} widget`, {
+                stage: "manifest",
+                detail: { appId: manifest.appId, expected: kind },
+            });
+        }
+    }
+    if (!manifest.layout.widgets.some((widget) => widget.kind === "table" || widget.kind === "list")) {
+        throw new HonuaGeneratedAppError("missing-widget", "operations dashboard manifest is missing table/list widget", {
+            stage: "manifest",
+            detail: { appId: manifest.appId, expected: "table|list" },
+        });
+    }
+}
+function findWidget(manifest, kind) {
+    return manifest.layout.widgets.find((widget) => widget.kind === kind);
+}
+function mapLayerIdForWidget(widget, manifest) {
+    return widget.layerId ?? manifest.bindings?.layerId;
+}
+function generatedAppQueryFields(manifest) {
+    const fields = [];
+    const add = (field) => {
+        if (field && !fields.includes(field))
+            fields.push(field);
+    };
+    const addMany = (values) => {
+        for (const field of values ?? [])
+            add(field);
+    };
+    add(manifest.bindings?.primaryKey ?? "OBJECTID");
+    add(manifest.bindings?.titleField);
+    add(manifest.bindings?.subtitleField);
+    add(manifest.bindings?.categoryField);
+    add(manifest.bindings?.filterField);
+    addMany(manifest.bindings?.tableFields);
+    addMany(manifest.bindings?.searchFields);
+    for (const widget of manifest.layout.widgets) {
+        switch (widget.kind) {
+            case "table":
+            case "list":
+                add(widget.primaryKey);
+                add(widget.titleField);
+                add(widget.subtitleField);
+                addMany(widget.fields);
+                break;
+            case "chart":
+                add(widget.groupBy);
+                add(widget.field);
+                if (widget.metric?.field !== "*")
+                    add(widget.metric?.field);
+                break;
+            case "filter":
+                add(widget.field);
+                break;
+            case "map":
+            case "count":
+                break;
+        }
+    }
+    return fields.length > 0 ? fields : undefined;
+}
+function assertMapPackageMatchesManifest(manifest, mapPackage) {
+    if (!manifest.mapPackageId || !mapPackage || manifest.mapPackageId === mapPackage.mapPackageId)
+        return;
+    throw new HonuaGeneratedAppError("map-package-mismatch", `generated-app MapPackage "${mapPackage.mapPackageId}" does not match manifest mapPackageId "${manifest.mapPackageId}"`, {
+        stage: "load",
+        detail: {
+            appId: manifest.appId,
+            path: "GeneratedAppManifest.mapPackageId",
+            expected: manifest.mapPackageId,
+            received: mapPackage.mapPackageId,
+        },
+    });
+}
+function missingWidgetBinding(appId, widgetId, widgetKind) {
+    return new HonuaGeneratedAppError("missing-binding", `generated-app widget "${widgetId}" is not bound`, {
+        stage: "interaction",
+        detail: { appId, widgetId, widgetKind },
+    });
+}
+function normalizeFeatureRecord(input, sourceId, primaryKey, index) {
+    const raw = input;
+    const attributes = asRecord(raw.attributes) ?? asRecord(raw.properties) ?? {};
+    const candidateId = raw.id ?? attributes[primaryKey] ?? attributes.OBJECTID ?? attributes.objectId ?? attributes.id;
+    const id = typeof candidateId === "string" || typeof candidateId === "number" ? candidateId : `${sourceId}:${index}`;
+    return {
+        id,
+        sourceId: typeof raw.sourceId === "string" ? raw.sourceId : sourceId,
+        attributes,
+        ...(raw.geometry !== undefined ? { geometry: raw.geometry } : {}),
+    };
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function applyProjection(records, filters, selection, sourceId) {
+    return records.filter((record) => Object.values(filters).every((clause) => matchesClause(record, clause, sourceId)) ||
+        selectionContains(selection, record, sourceId));
+}
+function applySortAndPagination(records, sort, page) {
+    const sorted = [...records];
+    for (const entry of [...sort].reverse()) {
+        sorted.sort((a, b) => compareValues(a.attributes[entry.field], b.attributes[entry.field], entry.direction));
+    }
+    const offset = page.offset ?? 0;
+    const limit = page.limit;
+    return limit === undefined ? sorted.slice(offset) : sorted.slice(offset, offset + limit);
+}
+function matchesClause(record, clause, fallbackSourceId) {
+    const sourceId = record.sourceId ?? fallbackSourceId;
+    if (clause.appliesTo && clause.appliesTo.length > 0 && !clause.appliesTo.includes(sourceId))
+        return true;
+    const value = record.attributes[clause.field];
+    switch (clause.operator) {
+        case "=":
+            return value === clause.value;
+        case "!=":
+            return value !== clause.value;
+        case "in":
+            return Array.isArray(clause.value) && clause.value.includes(value);
+        case "not-in":
+            return Array.isArray(clause.value) && !clause.value.includes(value);
+        case "like":
+            return typeof value === "string" && typeof clause.value === "string" && value.includes(clause.value);
+        case "is-null":
+            return value === null || value === undefined;
+        case "is-not-null":
+            return value !== null && value !== undefined;
+        case "<":
+            return typeof value === "number" && typeof clause.value === "number" && value < clause.value;
+        case "<=":
+            return typeof value === "number" && typeof clause.value === "number" && value <= clause.value;
+        case ">":
+            return typeof value === "number" && typeof clause.value === "number" && value > clause.value;
+        case ">=":
+            return typeof value === "number" && typeof clause.value === "number" && value >= clause.value;
+        case "between":
+            return (typeof value === "number" &&
+                Array.isArray(clause.value) &&
+                typeof clause.value[0] === "number" &&
+                typeof clause.value[1] === "number" &&
+                value >= clause.value[0] &&
+                value <= clause.value[1]);
+    }
+}
+function compileMapLibreFilters(filters, sourceId) {
+    const compiled = Object.values(filters)
+        .filter((clause) => !clause.appliesTo || clause.appliesTo.length === 0 || clause.appliesTo.includes(sourceId))
+        .map(clauseToMapLibreFilter)
+        .filter((entry) => Array.isArray(entry));
+    return compiled.length === 0 ? ["all"] : ["all", ...compiled];
+}
+function clauseToMapLibreFilter(clause) {
+    switch (clause.operator) {
+        case "=":
+            return ["==", clause.field, clause.value];
+        case "!=":
+            return ["!=", clause.field, clause.value];
+        case "in":
+            return Array.isArray(clause.value) ? ["in", clause.field, ...clause.value] : undefined;
+        case "not-in":
+            return Array.isArray(clause.value) ? ["!in", clause.field, ...clause.value] : undefined;
+        case "is-null":
+            return ["==", clause.field, null];
+        case "is-not-null":
+            return ["!=", clause.field, null];
+        default:
+            return undefined;
+    }
+}
+function chartBuckets(records, widget, sourceId, filters) {
+    const groupBy = chartCategoryField(widget);
+    if (!groupBy)
+        return [];
+    const buckets = new Map();
+    for (const record of records) {
+        const value = scalarBucketValue(record.attributes[groupBy]);
+        if (value === undefined)
+            continue;
+        const key = String(value);
+        const bucket = buckets.get(key) ?? { value, count: 0, targets: [] };
+        bucket.count += 1;
+        bucket.targets.push(sourceFeatureSelectionTarget(record.sourceId ?? sourceId, record.id));
+        buckets.set(key, bucket);
+    }
+    const active = filters[widget.id]?.value;
+    return [...buckets.values()]
+        .sort((a, b) => compareValues(a.value, b.value))
+        .map((bucket) => ({
+        value: bucket.value,
+        label: stringValue(bucket.value),
+        count: bucket.count,
+        selected: active === bucket.value,
+        targets: bucket.targets,
+    }));
+}
+function filterOptions(records, filters, widget, sourceId) {
+    const counts = new Map();
+    const active = filters[widget.id]?.value;
+    const explicit = widget.options ?? [];
+    for (const option of explicit) {
+        counts.set(String(option.value), { value: option.value, count: 0 });
+    }
+    for (const record of records) {
+        if (!Object.entries(filters).every(([id, clause]) => id === widget.id || matchesClause(record, clause, sourceId))) {
+            continue;
+        }
+        const value = scalarBucketValue(record.attributes[widget.field]);
+        if (value === undefined)
+            continue;
+        const key = String(value);
+        const entry = counts.get(key) ?? { value, count: 0 };
+        entry.count += 1;
+        counts.set(key, entry);
+    }
+    return [...counts.values()]
+        .sort((a, b) => compareValues(a.value, b.value))
+        .map((entry) => {
+        const configured = explicit.find((option) => option.value === entry.value);
+        return {
+            value: entry.value,
+            label: configured?.label ?? stringValue(entry.value),
+            count: entry.count,
+            selected: active === entry.value,
+        };
+    });
+}
+function chartModel(widget, filteredRecords, sourceId, filters, widgetModels) {
+    const chartKind = generatedChartKind(widget);
+    const base = {
+        id: widget.id,
+        kind: "chart",
+        chartKind,
+        ...(widget.title ? { title: widget.title } : {}),
+        sourceId,
+    };
+    if (chartKind === "histogram") {
+        const histogram = widgetModels?.histogram[widget.id] !== undefined
+            ? histogramBinsFromWidgetSource(widgetModels.histogram[widget.id])
+            : histogramBins(filteredRecords, chartMeasureField(widget), widget.bins, widget.min, widget.max);
+        return {
+            ...base,
+            field: chartMeasureField(widget),
+            buckets: [],
+            histogramBins: histogram,
+        };
+    }
+    if (chartKind === "time-series") {
+        const series = widgetModels?.timeSeries[widget.id] !== undefined
+            ? timeSeriesBucketsFromWidgetSource(widgetModels.timeSeries[widget.id])
+            : timeSeriesBuckets(filteredRecords, widget);
+        return {
+            ...base,
+            field: chartMeasureField(widget),
+            buckets: [],
+            timeSeriesBuckets: series.buckets,
+            interval: series.interval,
+        };
+    }
+    const groupBy = chartCategoryField(widget);
+    return {
+        ...base,
+        groupBy,
+        buckets: widgetModels?.categories[widget.id] !== undefined
+            ? chartBucketsFromWidgetSource(widgetModels.categories[widget.id], widget, filters)
+            : chartBuckets(filteredRecords, widget, sourceId, filters),
+    };
+}
+function chartBucketsFromWidgetSource(result, widget, filters) {
+    const active = filters[widget.id]?.value;
+    return result.buckets
+        .filter((bucket) => scalarBucketValue(bucket.value) !== undefined)
+        .map((bucket) => ({
+        value: bucket.value,
+        label: bucket.label,
+        count: bucket.count,
+        selected: active === bucket.value,
+        targets: [],
+    }));
+}
+function histogramBinsFromWidgetSource(result) {
+    return result.bins.map((bin) => ({
+        id: bin.id,
+        min: bin.min,
+        max: bin.max,
+        label: bin.label,
+        count: bin.count,
+        percent: bin.percent,
+    }));
+}
+function timeSeriesBucketsFromWidgetSource(result) {
+    return {
+        interval: result.interval,
+        buckets: result.buckets.map((bucket) => ({
+            id: bucket.id,
+            start: bucket.start,
+            end: bucket.end,
+            label: bucket.label,
+            count: bucket.count,
+            percent: bucket.percent,
+            ...(bucket.metric !== undefined ? { metric: bucket.metric } : {}),
+        })),
+    };
+}
+function generatedChartKind(widget) {
+    return widget.chartKind === "histogram" || widget.chartKind === "time-series" ? widget.chartKind : "categories";
+}
+function chartCategoryField(widget) {
+    if (generatedChartKind(widget) !== "categories")
+        return undefined;
+    return widget.groupBy ?? widget.field;
+}
+function chartMeasureField(widget) {
+    return widget.field ?? widget.groupBy ?? widget.metric?.field ?? "OBJECTID";
+}
+function histogramBins(records, field, requestedBins, requestedMin, requestedMax) {
+    const values = records.map((record) => numericValue(record.attributes[field])).filter(isNumber);
+    const min = requestedMin ?? minNumber(values);
+    const max = requestedMax ?? maxNumber(values);
+    if (min === undefined || max === undefined)
+        return [];
+    const count = clampInteger(requestedBins ?? 10, 1, 200);
+    const width = max === min ? 1 : (max - min) / count;
+    const bins = Array.from({ length: count }, (_, index) => {
+        const binMin = min + index * width;
+        const binMax = index === count - 1 ? max : min + (index + 1) * width;
+        return {
+            id: `${index}`,
+            min: binMin,
+            max: binMax,
+            label: `${formatNumber(binMin)} - ${formatNumber(binMax)}`,
+            count: 0,
+            percent: 0,
+        };
+    });
+    for (const value of values) {
+        if (value < min || value > max)
+            continue;
+        const index = max === min ? 0 : Math.min(count - 1, Math.floor((value - min) / width));
+        bins[index] = { ...bins[index], count: bins[index].count + 1 };
+    }
+    const total = bins.reduce((sum, bin) => sum + bin.count, 0);
+    return bins.map((bin) => ({ ...bin, percent: total > 0 ? bin.count / total : 0 }));
+}
+function timeSeriesBuckets(records, widget) {
+    const interval = normalizeWidgetInterval(widget.interval);
+    const field = chartMeasureField(widget);
+    const startLimit = dateValue(widget.start);
+    const endLimit = dateValue(widget.end);
+    const byStart = new Map();
+    for (const record of records) {
+        const date = dateValue(record.attributes[field]);
+        if (!date)
+            continue;
+        if (startLimit && date < startLimit)
+            continue;
+        if (endLimit && date >= endLimit)
+            continue;
+        const start = truncateWidgetDate(date, interval);
+        const key = start.toISOString();
+        const entry = byStart.get(key) ?? { start, end: addWidgetInterval(start, interval), count: 0, values: [] };
+        entry.count += 1;
+        if (widget.metric && widget.metric.fn !== "count") {
+            const value = numericValue(record.attributes[widget.metric.field]);
+            if (value !== undefined)
+                entry.values.push(value);
+        }
+        byStart.set(key, entry);
+    }
+    const working = [...byStart.values()].sort((a, b) => a.start.getTime() - b.start.getTime());
+    const filled = widget.fillMissing
+        ? fillMissingWidgetTimeBuckets(working, interval, widget.start, widget.end)
+        : working;
+    const total = filled.reduce((sum, bucket) => sum + bucket.count, 0);
+    return {
+        interval,
+        buckets: filled.map((bucket) => ({
+            id: bucket.start.toISOString(),
+            start: bucket.start.toISOString(),
+            end: bucket.end.toISOString(),
+            label: formatWidgetTimeLabel(bucket.start, interval),
+            count: bucket.count,
+            percent: total > 0 ? bucket.count / total : 0,
+            ...(widget.metric
+                ? {
+                    metric: widget.metric.fn === "count" ? bucket.count : computeWidgetMetric(bucket.values, widget.metric.fn),
+                }
+                : {}),
+        })),
+    };
+}
+function fillMissingWidgetTimeBuckets(buckets, interval, startValue, endValue) {
+    if (buckets.length === 0 && (startValue === undefined || endValue === undefined))
+        return buckets;
+    const first = dateValue(startValue) ?? buckets[0]?.start;
+    const lastEnd = dateValue(endValue) ?? buckets.at(-1)?.end;
+    if (!first || !lastEnd || first >= lastEnd)
+        return buckets;
+    const byStart = new Map(buckets.map((bucket) => [bucket.start.toISOString(), bucket]));
+    const out = [];
+    let cursor = truncateWidgetDate(first, interval);
+    while (cursor < lastEnd && out.length < 500) {
+        out.push(byStart.get(cursor.toISOString()) ?? {
+            start: new Date(cursor.getTime()),
+            end: addWidgetInterval(cursor, interval),
+            count: 0,
+            values: [],
+        });
+        cursor = addWidgetInterval(cursor, interval);
+    }
+    return out;
+}
+function filterOptionsFromWidgetSource(result, widget, filters) {
+    const active = filters[widget.id]?.value;
+    const byValue = new Map(result.buckets.map((bucket) => [String(bucket.value), bucket]));
+    const explicit = widget.options ?? [];
+    const buckets = explicit.length > 0
+        ? explicit.map((option) => ({
+            value: option.value,
+            label: option.label ?? stringValue(option.value),
+            count: byValue.get(String(option.value))?.count ?? 0,
+        }))
+        : result.buckets
+            .filter((bucket) => scalarBucketValue(bucket.value) !== undefined)
+            .map((bucket) => ({
+            value: bucket.value,
+            label: bucket.label,
+            count: bucket.count,
+        }));
+    return buckets.map((bucket) => ({
+        value: bucket.value,
+        label: bucket.label,
+        count: bucket.count,
+        selected: active === bucket.value,
+    }));
+}
+function selectionContains(selection, record, fallbackSourceId) {
+    const sourceId = record.sourceId ?? fallbackSourceId;
+    return selection.some((target) => {
+        if (isSourceQualifiedSelectionTarget(target))
+            return target.sourceId === sourceId && target.id === record.id;
+        return target === record.id;
+    });
+}
+function inferFields(records) {
+    const first = records[0];
+    return first ? Object.keys(first.attributes).slice(0, 6) : [];
+}
+function normalizeWidgetInterval(interval) {
+    return {
+        unit: interval?.unit ?? "day",
+        step: clampInteger(interval?.step ?? 1, 1, 10_000),
+        timezone: interval?.timezone ?? "UTC",
+    };
+}
+function dateValue(value) {
+    if (value instanceof Date && Number.isFinite(value.getTime()))
+        return new Date(value.getTime());
+    if (typeof value !== "string" && typeof value !== "number")
+        return undefined;
+    const date = new Date(value);
+    return Number.isFinite(date.getTime()) ? date : undefined;
+}
+function truncateWidgetDate(date, interval) {
+    const out = new Date(date.getTime());
+    const step = interval.step;
+    switch (interval.unit) {
+        case "minute":
+            out.setUTCSeconds(0, 0);
+            out.setUTCMinutes(Math.floor(out.getUTCMinutes() / step) * step);
+            return out;
+        case "hour":
+            out.setUTCMinutes(0, 0, 0);
+            out.setUTCHours(Math.floor(out.getUTCHours() / step) * step);
+            return out;
+        case "day":
+            return new Date(Date.UTC(out.getUTCFullYear(), out.getUTCMonth(), out.getUTCDate()));
+        case "week": {
+            const day = out.getUTCDay();
+            const mondayOffset = day === 0 ? 6 : day - 1;
+            return new Date(Date.UTC(out.getUTCFullYear(), out.getUTCMonth(), out.getUTCDate() - mondayOffset));
+        }
+        case "month":
+            return new Date(Date.UTC(out.getUTCFullYear(), Math.floor(out.getUTCMonth() / step) * step, 1));
+        case "quarter": {
+            const months = step * 3;
+            return new Date(Date.UTC(out.getUTCFullYear(), Math.floor(out.getUTCMonth() / months) * months, 1));
+        }
+        case "year":
+            return new Date(Date.UTC(Math.floor(out.getUTCFullYear() / step) * step, 0, 1));
+    }
+}
+function addWidgetInterval(date, interval) {
+    const out = new Date(date.getTime());
+    switch (interval.unit) {
+        case "minute":
+            out.setUTCMinutes(out.getUTCMinutes() + interval.step);
+            return out;
+        case "hour":
+            out.setUTCHours(out.getUTCHours() + interval.step);
+            return out;
+        case "day":
+            out.setUTCDate(out.getUTCDate() + interval.step);
+            return out;
+        case "week":
+            out.setUTCDate(out.getUTCDate() + interval.step * 7);
+            return out;
+        case "month":
+            out.setUTCMonth(out.getUTCMonth() + interval.step);
+            return out;
+        case "quarter":
+            out.setUTCMonth(out.getUTCMonth() + interval.step * 3);
+            return out;
+        case "year":
+            out.setUTCFullYear(out.getUTCFullYear() + interval.step);
+            return out;
+    }
+}
+function formatWidgetTimeLabel(date, interval) {
+    const iso = date.toISOString();
+    if (interval.unit === "year")
+        return iso.slice(0, 4);
+    if (interval.unit === "quarter")
+        return `${iso.slice(0, 4)} Q${Math.floor(date.getUTCMonth() / 3) + 1}`;
+    if (interval.unit === "month")
+        return iso.slice(0, 7);
+    if (interval.unit === "day" || interval.unit === "week")
+        return iso.slice(0, 10);
+    if (interval.unit === "hour")
+        return `${iso.slice(0, 13)}:00Z`;
+    return `${iso.slice(0, 16)}Z`;
+}
+function numericValue(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string" && value.trim() !== "") {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+function isNumber(value) {
+    return value !== undefined;
+}
+function computeWidgetMetric(values, fn) {
+    if (fn === "count")
+        return values.length;
+    if (values.length === 0)
+        return null;
+    switch (fn) {
+        case "sum":
+            return values.reduce((sum, value) => sum + value, 0);
+        case "avg":
+            return values.reduce((sum, value) => sum + value, 0) / values.length;
+        case "min":
+            return minNumber(values) ?? null;
+        case "max":
+            return maxNumber(values) ?? null;
+        case "stddev": {
+            const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
+            const variance = values.reduce((sum, value) => sum + (value - mean) ** 2, 0) / values.length;
+            return Math.sqrt(variance);
+        }
+        case "var": {
+            const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
+            return values.reduce((sum, value) => sum + (value - mean) ** 2, 0) / values.length;
+        }
+    }
+}
+function clampInteger(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.max(min, Math.min(max, Math.trunc(value)));
+}
+function minNumber(values) {
+    let min;
+    for (const value of values)
+        min = min === undefined || value < min ? value : min;
+    return min;
+}
+function maxNumber(values) {
+    let max;
+    for (const value of values)
+        max = max === undefined || value > max ? value : max;
+    return max;
+}
+function formatNumber(value) {
+    return Number.isInteger(value) ? String(value) : value.toFixed(2).replace(/\.?0+$/, "");
+}
+function compareValues(a, b, direction = "asc") {
+    const multiplier = direction === "desc" ? -1 : 1;
+    if (typeof a === "number" && typeof b === "number")
+        return (a - b) * multiplier;
+    return stringValue(a).localeCompare(stringValue(b)) * multiplier;
+}
+function scalarBucketValue(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : undefined;
+}
+function stringValue(value) {
+    return value === undefined || value === null ? "" : String(value);
+}
+function stableWidgetProjectionKey(projection) {
+    return stableStringify({
+        filters: projection.filters,
+        spatialFilter: projection.spatialFilter,
+        extent: projection.extent,
+        orderBy: projection.orderBy,
+        pagination: projection.pagination,
+        outFields: projection.outFields,
+        grouping: projection.grouping,
+        aggregation: projection.aggregation,
+        selection: projection.selection,
+    });
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const obj = value;
+    return `{${Object.keys(obj)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableStringify(obj[key])}`)
+        .join(",")}}`;
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+async function runWithConcurrency(tasks, concurrency) {
+    const limit = clampInteger(concurrency, 1, tasks.length || 1);
+    let next = 0;
+    async function worker() {
+        while (next < tasks.length) {
+            const task = tasks[next];
+            next += 1;
+            if (!task)
+                continue;
+            await task();
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(limit, tasks.length) }, () => worker()));
+}