@honua/app-platform 0.0.20-alpha.0

package/webmap/convert-basemap.js

@@ -0,0 +1,78 @@
+/**
+ * Converts Esri WebMap baseMap to Honua sources and layers.
+ *
+ * @module
+ */
+import { warnUnknownProperties } from "./warnings.js";
+export function convertBasemap(baseMap, warn) {
+    const result = { sources: {}, layers: [] };
+    if (!baseMap?.baseMapLayers)
+        return result;
+    warnUnknownProperties(baseMap, BASEMAP_PROPERTIES, warn);
+    const bmLayers = baseMap.baseMapLayers;
+    for (let i = 0; i < bmLayers.length; i++) {
+        const bml = bmLayers[i];
+        const bmlWarn = warn.child(`baseMapLayers[${i}]`);
+        warnUnknownProperties(bml, BASEMAP_LAYER_PROPERTIES, bmlWarn);
+        const sourceId = bml.id ?? `basemap-${i}`;
+        const layerId = `${sourceId}-layer`;
+        const layerType = bml.layerType ?? "";
+        if (layerType === "ArcGISTiledMapServiceLayer" && bml.url) {
+            result.sources[sourceId] = {
+                type: "honua-map-service",
+                url: bml.url,
+            };
+            const layer = {
+                id: layerId,
+                type: "raster",
+                source: sourceId,
+                layout: {},
+                paint: {},
+            };
+            if (bml.visibility === false) {
+                layer.layout = { visibility: "none" };
+            }
+            if (bml.opacity != null && bml.opacity < 1) {
+                layer.paint["raster-opacity"] = bml.opacity;
+            }
+            result.layers.push(layer);
+        }
+        else if (layerType === "VectorTileLayer") {
+            // Partial support: note styleUrl in metadata
+            if (bml.url) {
+                result.sources[sourceId] = {
+                    type: "vector",
+                    url: bml.url,
+                };
+            }
+            else {
+                bmlWarn.warn("missing-url", "VectorTileLayer missing url");
+                continue;
+            }
+            const layer = {
+                id: layerId,
+                type: "background",
+                source: sourceId,
+                layout: {},
+                paint: {},
+                metadata: {
+                    ...(bml.styleUrl ? { esriStyleUrl: bml.styleUrl } : {}),
+                    note: "VectorTileLayer requires style resolution; using placeholder background layer",
+                },
+            };
+            if (bml.visibility === false) {
+                layer.layout = { visibility: "none" };
+            }
+            bmlWarn.warn("vector-tile-partial", "VectorTileLayer support is partial; style must be resolved separately", {
+                styleUrl: bml.styleUrl,
+            });
+            result.layers.push(layer);
+        }
+        else {
+            bmlWarn.warn("unsupported-basemap-type", `Unsupported basemap layer type: ${layerType}`, { layerType });
+        }
+    }
+    return result;
+}
+const BASEMAP_PROPERTIES = ["title", "baseMapLayers"];
+const BASEMAP_LAYER_PROPERTIES = ["id", "title", "url", "layerType", "visibility", "opacity", "styleUrl"];

package/webmap/convert-extent.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Converts Esri WebMap extents/viewpoints to MapLibre center/zoom.
+ *
+ * Supports Web Mercator (WKID 3857 / 102100) and geographic (4326).
+ * Unsupported spatial references emit warnings and are skipped.
+ *
+ * @module
+ */
+import type { WebMapExtent, WebMapViewpoint } from "./types.js";
+import type { WarningCollector } from "./warnings.js";
+export interface ExtentConversionResult {
+    center: [number, number];
+    zoom: number;
+}
+export declare function convertInitialViewpoint(viewpoint: WebMapViewpoint | undefined, warn: WarningCollector): ExtentConversionResult | undefined;
+export declare function convertExtent(extent: WebMapExtent | undefined, warn: WarningCollector): ExtentConversionResult | undefined;
+//# sourceMappingURL=convert-extent.d.ts.map

package/webmap/convert-extent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert-extent.d.ts","sourceRoot":"","sources":["../../../src/webmap/convert-extent.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAe,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;CACd;AAMD,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,eAAe,GAAG,SAAS,EACtC,IAAI,EAAE,gBAAgB,GACrB,sBAAsB,GAAG,SAAS,CAsBpC;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,YAAY,GAAG,SAAS,EAChC,IAAI,EAAE,gBAAgB,GACrB,sBAAsB,GAAG,SAAS,CAyBpC"}

package/webmap/convert-extent.js

@@ -0,0 +1,114 @@
+/**
+ * Converts Esri WebMap extents/viewpoints to MapLibre center/zoom.
+ *
+ * Supports Web Mercator (WKID 3857 / 102100) and geographic (4326).
+ * Unsupported spatial references emit warnings and are skipped.
+ *
+ * @module
+ */
+const WEB_MERCATOR_WKIDS = new Set([3857, 102100, 102113]);
+const EARTH_RADIUS = 6378137;
+const ORIGIN_SHIFT = Math.PI * EARTH_RADIUS; // ~20037508.34
+export function convertInitialViewpoint(viewpoint, warn) {
+    if (!viewpoint?.targetGeometry)
+        return undefined;
+    const target = viewpoint.targetGeometry;
+    if (isExtent(target)) {
+        const extentResult = convertExtent(target, warn.child("targetGeometry"));
+        if (!extentResult)
+            return undefined;
+        if (viewpoint.scale != null) {
+            return {
+                center: extentResult.center,
+                zoom: scaleToZoom(viewpoint.scale),
+            };
+        }
+        return extentResult;
+    }
+    if (isPoint(target)) {
+        return convertPointViewpoint(target, viewpoint.scale, warn.child("targetGeometry"));
+    }
+    warn.warn("unsupported-viewpoint-geometry", "initialViewpoint.targetGeometry must be a point or extent");
+    return undefined;
+}
+export function convertExtent(extent, warn) {
+    if (!extent)
+        return undefined;
+    const wkid = extent.spatialReference?.latestWkid ?? extent.spatialReference?.wkid;
+    if (wkid && !WEB_MERCATOR_WKIDS.has(wkid)) {
+        // Check if it looks like geographic (4326)
+        if (wkid === 4326) {
+            return convertGeographicExtent(extent);
+        }
+        warn.warn("unsupported-spatial-reference", `Spatial reference WKID ${wkid} not supported; expected Web Mercator (3857)`, { wkid });
+        return undefined;
+    }
+    // Default assumption: if no SR specified and values are small, treat as geographic
+    if (!wkid && Math.abs(extent.xmin) <= 180 && Math.abs(extent.xmax) <= 180) {
+        return convertGeographicExtent(extent);
+    }
+    // Web Mercator → geographic
+    return convertMercatorExtent(extent);
+}
+function convertPointViewpoint(point, scale, warn) {
+    const wkid = point.spatialReference?.latestWkid ?? point.spatialReference?.wkid;
+    if (wkid && !WEB_MERCATOR_WKIDS.has(wkid) && wkid !== 4326) {
+        warn.warn("unsupported-spatial-reference", `Spatial reference WKID ${wkid} not supported; expected Web Mercator (3857) or WGS84 (4326)`, { wkid });
+        return undefined;
+    }
+    const isGeographic = wkid === 4326 || (!wkid && Math.abs(point.x) <= 180 && Math.abs(point.y) <= 90);
+    const center = isGeographic
+        ? [point.x, point.y]
+        : [round6(mercatorXToLng(point.x)), round6(mercatorYToLat(point.y))];
+    return {
+        center,
+        zoom: scale != null ? scaleToZoom(scale) : 10,
+    };
+}
+function convertGeographicExtent(extent) {
+    const centerLng = (extent.xmin + extent.xmax) / 2;
+    const centerLat = (extent.ymin + extent.ymax) / 2;
+    const lngSpan = extent.xmax - extent.xmin;
+    // Approximate zoom from longitude span: 360/2^zoom ≈ lngSpan
+    const zoom = lngSpan > 0 ? Math.round(Math.log2(360 / lngSpan) * 100) / 100 : 2;
+    return { center: [centerLng, centerLat], zoom };
+}
+function convertMercatorExtent(extent) {
+    const centerX = (extent.xmin + extent.xmax) / 2;
+    const centerY = (extent.ymin + extent.ymax) / 2;
+    const centerLng = mercatorXToLng(centerX);
+    const centerLat = mercatorYToLat(centerY);
+    // Zoom from mercator extent width
+    const xSpan = extent.xmax - extent.xmin;
+    const fullWidth = ORIGIN_SHIFT * 2;
+    const zoom = xSpan > 0 ? Math.round(Math.log2(fullWidth / xSpan) * 100) / 100 : 2;
+    return {
+        center: [round6(centerLng), round6(centerLat)],
+        zoom,
+    };
+}
+function scaleToZoom(scale) {
+    if (scale <= 0)
+        return 0;
+    return Math.round(Math.log2(559082264 / scale) * 100) / 100;
+}
+function round6(value) {
+    return Math.round(value * 1e6) / 1e6;
+}
+function isExtent(value) {
+    return (typeof value.xmin === "number" &&
+        typeof value.ymin === "number" &&
+        typeof value.xmax === "number" &&
+        typeof value.ymax === "number");
+}
+function isPoint(value) {
+    return typeof value.x === "number" && typeof value.y === "number";
+}
+function mercatorXToLng(x) {
+    return (x / ORIGIN_SHIFT) * 180;
+}
+function mercatorYToLat(y) {
+    let lat = (y / ORIGIN_SHIFT) * 180;
+    lat = (180 / Math.PI) * (2 * Math.atan(Math.exp((lat * Math.PI) / 180)) - Math.PI / 2);
+    return lat;
+}

package/webmap/convert-label.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Converts Esri labelingInfo to MapLibre symbol layers.
+ *
+ * Supports basic Arcade expressions like `$feature.FIELD_NAME`.
+ * Complex Arcade expressions emit a warning and are skipped.
+ *
+ * @module
+ */
+import type { HonuaLayerSpecification } from "../style/specification.js";
+import type { WebMapLabelClass } from "./types.js";
+import type { WarningCollector } from "./warnings.js";
+export declare function convertLabelingInfo(labelClasses: WebMapLabelClass[] | undefined, sourceId: string, baseLayerId: string, warn: WarningCollector): HonuaLayerSpecification[];
+//# sourceMappingURL=convert-label.d.ts.map

package/webmap/convert-label.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert-label.d.ts","sourceRoot":"","sources":["../../../src/webmap/convert-label.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAEzE,OAAO,KAAK,EAAE,gBAAgB,EAAoB,MAAM,YAAY,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,gBAAgB,EAAE,GAAG,SAAS,EAC5C,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,gBAAgB,GACrB,uBAAuB,EAAE,CAyC3B"}

package/webmap/convert-label.js

@@ -0,0 +1,125 @@
+/**
+ * Converts Esri labelingInfo to MapLibre symbol layers.
+ *
+ * Supports basic Arcade expressions like `$feature.FIELD_NAME`.
+ * Complex Arcade expressions emit a warning and are skipped.
+ *
+ * @module
+ */
+import { esriColorToCss } from "./convert-symbol.js";
+export function convertLabelingInfo(labelClasses, sourceId, baseLayerId, warn) {
+    if (!labelClasses || labelClasses.length === 0)
+        return [];
+    const layers = [];
+    for (let i = 0; i < labelClasses.length; i++) {
+        const lc = labelClasses[i];
+        const lcWarn = warn.child(`labelingInfo[${i}]`);
+        const textExpr = parseLabelExpression(lc, lcWarn);
+        if (!textExpr)
+            continue;
+        const layer = {
+            id: `${baseLayerId}-label-${i}`,
+            type: "symbol",
+            source: sourceId,
+            layout: {
+                "text-field": textExpr,
+                "text-size": 12,
+            },
+            paint: {},
+        };
+        // Apply symbol styling
+        if (lc.symbol) {
+            applyTextSymbolStyle(lc.symbol, layer);
+        }
+        // Apply scale constraints
+        if (lc.minScale)
+            layer.maxzoom = scaleToZoom(lc.minScale);
+        if (lc.maxScale)
+            layer.minzoom = scaleToZoom(lc.maxScale);
+        // Apply where clause as filter
+        if (lc.where) {
+            layer.metadata = { ...layer.metadata, esriWhere: lc.where };
+        }
+        layers.push(layer);
+    }
+    return layers;
+}
+const FEATURE_FIELD_RE = /^\$feature\.(\w+)$/;
+const FEATURE_FIELD_GLOBAL_RE = /\$feature\.(\w+)/g;
+function parseLabelExpression(lc, warn) {
+    // Prefer labelExpressionInfo (Arcade-based)
+    if (lc.labelExpressionInfo?.expression) {
+        const expr = lc.labelExpressionInfo.expression;
+        // Simple: $feature.FIELD_NAME
+        const simple = expr.match(FEATURE_FIELD_RE);
+        if (simple) {
+            return ["get", simple[1]];
+        }
+        // Try concatenation patterns: $feature.A + " " + $feature.B
+        if (expr.includes("$feature.") && !expr.includes("(")) {
+            return parseSimpleConcatExpression(expr, warn);
+        }
+        warn.warn("complex-arcade", `Complex Arcade expression not supported: ${expr}`);
+        return undefined;
+    }
+    // Fallback: labelExpression (e.g., "[FIELD_NAME]")
+    if (lc.labelExpression) {
+        const bracketMatch = lc.labelExpression.match(/^\[(\w+)\]$/);
+        if (bracketMatch) {
+            return ["get", bracketMatch[1]];
+        }
+        warn.warn("complex-label-expression", `Complex label expression not supported: ${lc.labelExpression}`);
+        return undefined;
+    }
+    // Fallback: value template
+    if (lc.labelExpressionInfo?.value) {
+        const value = lc.labelExpressionInfo.value;
+        const fieldMatch = value.match(/^\{(\w+)\}$/);
+        if (fieldMatch) {
+            return ["get", fieldMatch[1]];
+        }
+    }
+    return undefined;
+}
+function parseSimpleConcatExpression(expr, warn) {
+    // Handle: $feature.A + " " + $feature.B
+    const parts = expr.split("+").map((p) => p.trim());
+    const concatArgs = [];
+    for (const part of parts) {
+        const fieldMatch = part.match(FEATURE_FIELD_RE);
+        if (fieldMatch) {
+            concatArgs.push(["get", fieldMatch[1]]);
+        }
+        else if ((part.startsWith('"') && part.endsWith('"')) || (part.startsWith("'") && part.endsWith("'"))) {
+            concatArgs.push(part.slice(1, -1));
+        }
+        else {
+            warn.warn("complex-arcade", `Cannot parse Arcade expression part: ${part}`);
+            return undefined;
+        }
+    }
+    if (concatArgs.length === 1)
+        return concatArgs[0];
+    return ["concat", ...concatArgs];
+}
+function applyTextSymbolStyle(symbol, layer) {
+    if (symbol.color) {
+        const color = esriColorToCss(symbol.color);
+        if (color)
+            layer.paint["text-color"] = color;
+    }
+    if (symbol.font) {
+        const layout = layer.layout;
+        if (symbol.font.size != null)
+            layout["text-size"] = symbol.font.size;
+        if (symbol.font.family)
+            layout["text-font"] = [symbol.font.family];
+    }
+}
+/** Approximate Esri scale denominator to MapLibre zoom level. */
+function scaleToZoom(scale) {
+    if (scale <= 0)
+        return 0;
+    // Esri uses 96 DPI; at zoom 0, scale ≈ 559082264
+    return Math.round(Math.log2(559082264 / scale) * 100) / 100;
+}

package/webmap/convert-layer.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Converts a single WebMap operational layer to Honua source(s) and layer(s).
+ *
+ * Orchestrates per-layer conversion: determines source type from layerType/url,
+ * calls renderer/popup/label converters, applies opacity/visibility/min-maxScale.
+ *
+ * @module
+ */
+import type { HonuaLayerSpecification, HonuaSourceSpecification } from "../style/specification.js";
+import { type HonuaPopupConfig } from "./convert-popup.js";
+import type { WebMapOperationalLayer } from "./types.js";
+import { type WarningCollector } from "./warnings.js";
+export interface LayerConversionResult {
+    sources: Record<string, HonuaSourceSpecification | {
+        type: string;
+        [key: string]: unknown;
+    }>;
+    layers: HonuaLayerSpecification[];
+    popup?: HonuaPopupConfig;
+}
+export declare function convertOperationalLayer(opLayer: WebMapOperationalLayer, index: number, warn: WarningCollector): LayerConversionResult;
+//# sourceMappingURL=convert-layer.d.ts.map

package/webmap/convert-layer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert-layer.d.ts","sourceRoot":"","sources":["../../../src/webmap/convert-layer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAEV,uBAAuB,EAEvB,wBAAwB,EACzB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,KAAK,gBAAgB,EAAoB,MAAM,oBAAoB,CAAC;AAE7E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,KAAK,gBAAgB,EAAyB,MAAM,eAAe,CAAC;AAE7E,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC;IAC7F,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAClC,KAAK,CAAC,EAAE,gBAAgB,CAAC;CAC1B;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,gBAAgB,GACrB,qBAAqB,CAmHvB"}

package/webmap/convert-layer.js

@@ -0,0 +1,181 @@
+/**
+ * Converts a single WebMap operational layer to Honua source(s) and layer(s).
+ *
+ * Orchestrates per-layer conversion: determines source type from layerType/url,
+ * calls renderer/popup/label converters, applies opacity/visibility/min-maxScale.
+ *
+ * @module
+ */
+import { convertLabelingInfo } from "./convert-label.js";
+import { convertPopupInfo } from "./convert-popup.js";
+import { convertRenderer } from "./convert-renderer.js";
+import { warnUnknownProperties } from "./warnings.js";
+export function convertOperationalLayer(opLayer, index, warn) {
+    const result = { sources: {}, layers: [] };
+    const layerWarn = warn.child(`operationalLayers[${index}]`);
+    warnUnknownProperties(opLayer, OPERATIONAL_LAYER_PROPERTIES, layerWarn);
+    detectUnsupported3DLayerProperties(opLayer, layerWarn);
+    const sourceId = opLayer.id ?? `operational-${index}`;
+    const layerId = sourceId;
+    // Determine source type
+    const layerType = opLayer.layerType ?? "";
+    const url = opLayer.url ?? "";
+    if (layerType === "ArcGISFeatureLayer" || url.includes("FeatureServer")) {
+        const source = {
+            type: "honua-feature-service",
+            url,
+        };
+        if (opLayer.layerDefinition?.definitionExpression) {
+            source.definitionExpression = opLayer.layerDefinition.definitionExpression;
+        }
+        result.sources[sourceId] = source;
+    }
+    else if (layerType === "ArcGISMapServiceLayer" || url.includes("MapServer")) {
+        const source = {
+            type: "honua-map-service",
+            url,
+        };
+        result.sources[sourceId] = source;
+    }
+    else if (opLayer.featureCollection) {
+        layerWarn.warn("unsupported-feature-collection", "Inline feature collections are not supported");
+        return result;
+    }
+    else {
+        layerWarn.warn("unsupported-layer-type", `Unsupported layer type: ${layerType}`, { layerType, url });
+        return result;
+    }
+    warnUnknownProperties(opLayer.layerDefinition, LAYER_DEFINITION_PROPERTIES, layerWarn.child("layerDefinition"));
+    warnUnknownProperties(opLayer.layerDefinition?.drawingInfo, DRAWING_INFO_PROPERTIES, layerWarn.child("layerDefinition.drawingInfo"));
+    // Convert renderer
+    const renderer = opLayer.layerDefinition?.drawingInfo?.renderer;
+    const rendererResult = convertRenderer(renderer, layerWarn.child("layerDefinition.drawingInfo.renderer"));
+    if (rendererResult) {
+        const layer = {
+            id: layerId,
+            type: rendererResult.layerType,
+            source: sourceId,
+            paint: { ...rendererResult.paint },
+            layout: { ...rendererResult.layout },
+        };
+        // Apply transparency from drawingInfo
+        const transparency = opLayer.layerDefinition?.drawingInfo?.transparency;
+        if (transparency != null && transparency > 0) {
+            applyTransparency(layer, transparency);
+        }
+        // Apply layer-level opacity
+        if (opLayer.opacity != null && opLayer.opacity < 1) {
+            applyOpacity(layer, opLayer.opacity);
+        }
+        // Apply visibility
+        if (opLayer.visibility === false) {
+            layer.layout = { ...layer.layout, visibility: "none" };
+        }
+        // Apply scale constraints
+        if (opLayer.minScale)
+            layer.maxzoom = scaleToZoom(opLayer.minScale);
+        if (opLayer.maxScale)
+            layer.minzoom = scaleToZoom(opLayer.maxScale);
+        // Store title in metadata
+        if (opLayer.title) {
+            layer.metadata = { ...layer.metadata, title: opLayer.title };
+        }
+        result.layers.push(layer);
+    }
+    else if (!renderer) {
+        // No renderer — create a default layer so the source is referenced
+        const layer = {
+            id: layerId,
+            type: "circle",
+            source: sourceId,
+            paint: { "circle-radius": 4, "circle-color": "#007cbf" },
+            layout: {},
+        };
+        if (opLayer.visibility === false) {
+            layer.layout = { visibility: "none" };
+        }
+        if (opLayer.minScale)
+            layer.maxzoom = scaleToZoom(opLayer.minScale);
+        if (opLayer.maxScale)
+            layer.minzoom = scaleToZoom(opLayer.maxScale);
+        if (opLayer.title)
+            layer.metadata = { title: opLayer.title };
+        result.layers.push(layer);
+    }
+    // Convert labels
+    const labelLayers = convertLabelingInfo(opLayer.layerDefinition?.drawingInfo?.labelingInfo, sourceId, layerId, layerWarn.child("layerDefinition.drawingInfo"));
+    result.layers.push(...labelLayers);
+    // Convert popup
+    result.popup = convertPopupInfo(opLayer.popupInfo, layerWarn.child("popupInfo"));
+    return result;
+}
+function applyTransparency(layer, transparency) {
+    const opacity = 1 - transparency / 100;
+    applyOpacity(layer, opacity);
+}
+function applyOpacity(layer, opacity) {
+    const paint = layer.paint;
+    switch (layer.type) {
+        case "fill":
+            paint["fill-opacity"] = opacity;
+            break;
+        case "line":
+            paint["line-opacity"] = opacity;
+            break;
+        case "circle":
+            paint["circle-opacity"] = opacity;
+            break;
+        case "symbol":
+            paint["icon-opacity"] = opacity;
+            paint["text-opacity"] = opacity;
+            break;
+        case "raster":
+            paint["raster-opacity"] = opacity;
+            break;
+    }
+}
+function scaleToZoom(scale) {
+    if (scale <= 0)
+        return 0;
+    return Math.round(Math.log2(559082264 / scale) * 100) / 100;
+}
+const OPERATIONAL_LAYER_PROPERTIES = [
+    "id",
+    "title",
+    "url",
+    "layerType",
+    "itemId",
+    "visibility",
+    "opacity",
+    "minScale",
+    "maxScale",
+    "layerDefinition",
+    "popupInfo",
+    "featureCollection",
+    "layers",
+    "mode",
+];
+const LAYER_DEFINITION_PROPERTIES = ["drawingInfo", "definitionExpression", "minScale", "maxScale"];
+const DRAWING_INFO_PROPERTIES = ["renderer", "labelingInfo", "transparency"];
+const LAYER_3D_PROPERTIES = ["elevationInfo", "heightInfo", "sceneProperties"];
+function detectUnsupported3DLayerProperties(opLayer, warn) {
+    const layerType = typeof opLayer.layerType === "string" ? opLayer.layerType : "";
+    if (layerType.toLowerCase().includes("scene")) {
+        warn.warn("unsupported-3d-property", `Layer type '${layerType}' requires a scene renderer adapter`, {
+            layerType,
+            status: "unsupported",
+            fallback: "Preserve the service URL as scene-layer metadata or model-layer primitives; omit it from the 2D style.",
+        });
+    }
+    for (const key of LAYER_3D_PROPERTIES) {
+        if (Object.prototype.hasOwnProperty.call(opLayer, key)) {
+            warn.warn("unsupported-3d-property", `Layer property '${key}' is not supported by the 2D WebMap style path`, {
+                property: key,
+                status: key === "elevationInfo" || key === "heightInfo" ? "degraded" : "unsupported",
+                fallback: key === "elevationInfo" || key === "heightInfo"
+                    ? "MapLibre extrusion/terrain primitives can represent simple height and elevation behavior."
+                    : "Preserve this property for a scene renderer adapter.",
+            });
+        }
+    }
+}

package/webmap/convert-popup.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Converts Esri popupInfo to Honua popup configuration.
+ *
+ * Since MapLibre has no popup specification, popup configuration is
+ * stored outside the style as metadata.
+ *
+ * @module
+ */
+import type { WebMapPopupInfo } from "./types.js";
+import { type WarningCollector } from "./warnings.js";
+export interface HonuaPopupFieldInfo {
+    fieldName: string;
+    label?: string;
+    visible: boolean;
+    format?: {
+        places?: number;
+        digitSeparator?: boolean;
+        dateFormat?: string;
+    };
+}
+export interface HonuaPopupMediaInfo {
+    type: string;
+    title?: string;
+    caption?: string;
+    value?: Record<string, unknown>;
+}
+export interface HonuaPopupConfig {
+    title?: string;
+    description?: string;
+    fieldInfos: HonuaPopupFieldInfo[];
+    mediaInfos: HonuaPopupMediaInfo[];
+}
+export declare function convertPopupInfo(popupInfo: WebMapPopupInfo | undefined, warn?: WarningCollector): HonuaPopupConfig | undefined;
+//# sourceMappingURL=convert-popup.d.ts.map

package/webmap/convert-popup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert-popup.d.ts","sourceRoot":"","sources":["../../../src/webmap/convert-popup.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAoC,eAAe,EAAE,MAAM,YAAY,CAAC;AACpF,OAAO,EAAE,KAAK,gBAAgB,EAAyB,MAAM,eAAe,CAAC;AAE7E,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE;QACP,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAClC,UAAU,EAAE,mBAAmB,EAAE,CAAC;CACnC;AAED,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,eAAe,GAAG,SAAS,EACtC,IAAI,CAAC,EAAE,gBAAgB,GACtB,gBAAgB,GAAG,SAAS,CAyB9B"}

package/webmap/convert-popup.js

@@ -0,0 +1,68 @@
+/**
+ * Converts Esri popupInfo to Honua popup configuration.
+ *
+ * Since MapLibre has no popup specification, popup configuration is
+ * stored outside the style as metadata.
+ *
+ * @module
+ */
+import { warnUnknownProperties } from "./warnings.js";
+export function convertPopupInfo(popupInfo, warn) {
+    if (!popupInfo)
+        return undefined;
+    if (warn) {
+        warnUnknownProperties(popupInfo, POPUP_INFO_PROPERTIES, warn);
+        const expressionInfos = popupInfo.expressionInfos;
+        if (Array.isArray(expressionInfos) && expressionInfos.length > 0) {
+            warn.warn("unsupported-arcade-expression", "popupInfo.expressionInfos is not supported; Arcade expressions require manual intervention", { count: expressionInfos.length });
+        }
+    }
+    return {
+        title: popupInfo.title,
+        description: popupInfo.description,
+        fieldInfos: (popupInfo.fieldInfos ?? []).map((fieldInfo, index) => convertFieldInfo(fieldInfo, warn?.child(`fieldInfos[${index}]`))),
+        mediaInfos: (popupInfo.mediaInfos ?? []).map((mediaInfo, index) => convertMediaInfo(mediaInfo, warn?.child(`mediaInfos[${index}]`))),
+    };
+}
+function convertFieldInfo(info, warn) {
+    if (warn) {
+        warnUnknownProperties(info, POPUP_FIELD_INFO_PROPERTIES, warn);
+        warnUnknownProperties(info.format, POPUP_FIELD_FORMAT_PROPERTIES, warn.child("format"));
+    }
+    return {
+        fieldName: info.fieldName ?? "",
+        label: info.label,
+        visible: info.visible !== false,
+        ...(info.format
+            ? {
+                format: {
+                    ...(info.format.places != null ? { places: info.format.places } : {}),
+                    ...(info.format.digitSeparator != null ? { digitSeparator: info.format.digitSeparator } : {}),
+                    ...(info.format.dateFormat ? { dateFormat: info.format.dateFormat } : {}),
+                },
+            }
+            : {}),
+    };
+}
+function convertMediaInfo(info, warn) {
+    if (warn) {
+        warnUnknownProperties(info, POPUP_MEDIA_INFO_PROPERTIES, warn);
+    }
+    return {
+        type: info.type ?? "unknown",
+        ...(info.title ? { title: info.title } : {}),
+        ...(info.caption ? { caption: info.caption } : {}),
+        ...(info.value ? { value: info.value } : {}),
+    };
+}
+const POPUP_INFO_PROPERTIES = [
+    "title",
+    "description",
+    "fieldInfos",
+    "mediaInfos",
+    "showAttachments",
+    "expressionInfos",
+];
+const POPUP_FIELD_INFO_PROPERTIES = ["fieldName", "label", "tooltip", "visible", "isEditable", "format"];
+const POPUP_FIELD_FORMAT_PROPERTIES = ["places", "digitSeparator", "dateFormat"];
+const POPUP_MEDIA_INFO_PROPERTIES = ["type", "title", "caption", "value"];