@faclon-labs/app-sdk 0.1.0 → 0.2.0

package/vendor/map-engine/maplibre/style.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Pure translation from engine layers and basemap config to MapLibre style objects.
+ * Generic visualization only — nothing here knows what an object represents.
+ */
+import type { BasemapConfig, MapLayer, StyleRule, StyleTokens, TerrainConfig } from '../core/types.js';
+/** Font name used in `text-font` when the basemap supplies a label font. */
+export declare const LABEL_FONT = "me-label";
+export interface RendererTheme {
+    markerColor: string;
+    lineColor: string;
+    fillColor: string;
+    selectionColor: string;
+    hoverColor: string;
+    background: string;
+    labelColor: string;
+    labelHalo: string;
+    clusterColor: string;
+    clusterRing: string;
+    clusterText: string;
+    heatLow: string;
+    heatMid: string;
+    heatHigh: string;
+    heatMax: string;
+    trackColor: string;
+    /** Sky and horizon when the camera tilts or the map is a globe (phase 3B). */
+    skyColor: string;
+    horizonColor: string;
+    hillshadeShadow: string;
+    hillshadeHighlight: string;
+    contourColor: string;
+}
+export declare const DEFAULT_THEME: RendererTheme;
+/** Source options for an engine layer: clustering is a GeoJSON source option. */
+export declare function sourceSpecFor(layer: MapLayer): Record<string, unknown>;
+/** Source and layer ids of the terrain the renderer adds under the engine's layers (phase 3B). */
+export declare const TERRAIN_SOURCE = "me:terrain-dem";
+export declare const HILLSHADE_SOURCE = "me:hillshade-dem";
+export declare const HILLSHADE_LAYER = "me:hillshade";
+/** A raster-dem source for a terrain config (one for the 3D surface, one for hillshade: MapLibre advises two). */
+/** A `pmtiles://` archive is one URL (MapLibre reads its tiles through the pmtiles protocol), not a tile template. */
+export declare const isPmtiles: (url: string | undefined) => boolean;
+export declare function demSourceFor(terrain: TerrainConfig): Record<string, unknown>;
+/** Relief shading from the terrain, drawn under every engine layer. */
+export declare function hillshadeLayer(theme: RendererTheme): Record<string, unknown>;
+export declare const CONTOUR_SOURCE = "me:contours";
+export declare const CONTOUR_LINES = "me:contour-lines";
+export declare const CONTOUR_LABELS = "me:contour-labels";
+/** Contour lines (doc 28 G11) from a vector source of `contours` features with `ele` and `level` (1 = index line). */
+export declare function contourLayers(theme: RendererTheme, color: string | undefined, hasFont: boolean): Array<Record<string, unknown>>;
+/** Images a layer needs registered before its symbol layers render. */
+export declare function imagesFor(layer: MapLayer): Array<{
+    id: string;
+    shape?: NonNullable<MapLayer['visualization']['icon']>['shape'];
+    url?: string;
+}>;
+/** Prefix for every source and style layer the engine owns, so basemap layers are never touched. */
+export declare const PREFIX = "me";
+export declare const sourceId: (layerId: string) => string;
+export declare const OBJECT_ID_PROP = "__oid";
+export declare const LAYER_ID_PROP = "__lid";
+/** Marks the one label point an area gets in its own source (so a large area is labelled once, not once per tile). */
+export declare const LABEL_POINT_PROP = "__lp";
+/** Area layers with a label carry a label point per object next to the shape. */
+export declare function needsLabelPoints(layer: MapLayer): boolean;
+/** Data-driven dashes (StyleTokens.dash), first matching rule wins; null when no rule asks for dashes. */
+export declare function dashExpression(rules: StyleRule[] | undefined): unknown;
+export type StyleLayerSpec = Record<string, unknown> & {
+    id: string;
+    type: string;
+    source?: string;
+};
+/** MapLibre style for the configured basemap. 'none' needs no network at all. */
+export declare function basemapStyle(basemap: BasemapConfig, theme: RendererTheme): string | Record<string, unknown>;
+/**
+ * A fetched street-map style with the engine's label font added (MapLibre v6 font-faces) and its relative URLs
+ * made absolute, so it can be passed as an object.
+ */
+export declare function withLabelFont(style: Record<string, unknown>, styleUrl: string, fontUrl: string): Record<string, unknown>;
+/** The MapLibre condition for one rule, or null when the rule cannot be expressed (it is then skipped). */
+export declare function ruleCondition(rule: StyleRule): unknown | null;
+/** A token's expression: a continuous scale's per-object value (`$s:<token>`) first, then the rules. */
+export declare function tokenExpression<K extends keyof StyleTokens>(rules: StyleRule[] | undefined, key: K, fallback: NonNullable<StyleTokens[K]>): unknown;
+/** The MapLibre style layers for one engine layer, bottom to top. Labels need a label font (`hasFont`). */
+export declare function styleLayersFor(layer: MapLayer, theme: RendererTheme, hasFont?: boolean): StyleLayerSpec[];

package/vendor/map-engine/maplibre/style.js

@@ -0,0 +1,493 @@
+import { ICON_PIXELS, shapeImageId, urlImageId } from './icons.js';
+import { hostedByDeck } from './deck-host.js';
+import { scaled } from '../present/present.js';
+/** Font name used in `text-font` when the basemap supplies a label font. */
+export const LABEL_FONT = 'me-label';
+export const DEFAULT_THEME = {
+    skyColor: '#7FB2E5',
+    horizonColor: '#DCE8F2',
+    hillshadeShadow: '#2B2B2B',
+    hillshadeHighlight: '#FFFFFF',
+    contourColor: '#8A6F4E',
+    markerColor: '#4CC3FF',
+    lineColor: '#C9A66B',
+    fillColor: '#4CC3FF',
+    selectionColor: '#FFD43B',
+    hoverColor: '#FFFFFF',
+    background: '#0E1512',
+    labelColor: '#DCE5DF',
+    labelHalo: '#0B100E',
+    clusterColor: '#1E6F95',
+    clusterRing: '#4CC3FF',
+    clusterText: '#FFFFFF',
+    heatLow: '#1E6F95',
+    heatMid: '#4CC3FF',
+    heatHigh: '#FFD43B',
+    heatMax: '#FF5A4E',
+    trackColor: '#4CC3FF',
+};
+/** Source options for an engine layer: clustering is a GeoJSON source option. */
+export function sourceSpecFor(layer) {
+    const c = layer.visualization.type === 'marker' ? layer.visualization.cluster : undefined;
+    return {
+        type: 'geojson',
+        data: { type: 'FeatureCollection', features: [] },
+        ...(c ? { cluster: true, clusterRadius: c.radius ?? 50, clusterMaxZoom: c.maxZoom ?? 14 } : {}),
+    };
+}
+/** Source and layer ids of the terrain the renderer adds under the engine's layers (phase 3B). */
+export const TERRAIN_SOURCE = `${'me'}:terrain-dem`;
+export const HILLSHADE_SOURCE = `${'me'}:hillshade-dem`;
+export const HILLSHADE_LAYER = `${'me'}:hillshade`;
+/** A raster-dem source for a terrain config (one for the 3D surface, one for hillshade: MapLibre advises two). */
+/** A `pmtiles://` archive is one URL (MapLibre reads its tiles through the pmtiles protocol), not a tile template. */
+export const isPmtiles = (url) => !!url && /^pmtiles:\/\//i.test(url);
+const tilesOrUrl = (url) => (isPmtiles(url) ? { url } : { tiles: [url] });
+export function demSourceFor(terrain) {
+    return {
+        type: 'raster-dem',
+        ...tilesOrUrl(terrain.tileUrl),
+        tileSize: terrain.tileSize ?? 256,
+        maxzoom: terrain.maxZoom ?? 15,
+        encoding: terrain.encoding ?? 'terrarium',
+        ...(terrain.attribution ? { attribution: terrain.attribution } : {}),
+    };
+}
+/** Relief shading from the terrain, drawn under every engine layer. */
+export function hillshadeLayer(theme) {
+    return {
+        id: HILLSHADE_LAYER,
+        type: 'hillshade',
+        source: HILLSHADE_SOURCE,
+        paint: { 'hillshade-exaggeration': 0.35, 'hillshade-shadow-color': theme.hillshadeShadow, 'hillshade-highlight-color': theme.hillshadeHighlight },
+    };
+}
+export const CONTOUR_SOURCE = `${'me'}:contours`;
+export const CONTOUR_LINES = `${'me'}:contour-lines`;
+export const CONTOUR_LABELS = `${'me'}:contour-labels`;
+/** Contour lines (doc 28 G11) from a vector source of `contours` features with `ele` and `level` (1 = index line). */
+export function contourLayers(theme, color, hasFont) {
+    const c = color ?? theme.contourColor;
+    return [
+        { id: CONTOUR_LINES, type: 'line', source: CONTOUR_SOURCE, 'source-layer': 'contours', paint: { 'line-color': c, 'line-opacity': 0.55, 'line-width': ['match', ['get', 'level'], 1, 1.1, 0.5] } },
+        ...(hasFont
+            ? [{ id: CONTOUR_LABELS, type: 'symbol', source: CONTOUR_SOURCE, 'source-layer': 'contours', filter: ['>', ['get', 'level'], 0], layout: { 'symbol-placement': 'line', 'text-field': ['concat', ['number-format', ['get', 'ele'], {}], ' m'], 'text-font': [LABEL_FONT], 'text-size': 10 }, paint: { 'text-color': c, 'text-halo-color': 'rgba(255,255,255,0.85)', 'text-halo-width': 1.4 } }]
+            : []),
+    ];
+}
+/** Images a layer needs registered before its symbol layers render. */
+export function imagesFor(layer) {
+    const icon = layer.visualization.type === 'marker' ? layer.visualization.icon : undefined;
+    if (!icon)
+        return [];
+    const base = icon.shape ? [{ id: shapeImageId(icon.shape), shape: icon.shape }] : icon.imageUrl ? [{ id: urlImageId(icon.imageUrl), url: icon.imageUrl }] : [];
+    // Per-rule images (an icon per status, threat, …).
+    const perRule = (layer.visualization.style ?? []).flatMap((r) => (r.style.imageUrl ? [{ id: urlImageId(r.style.imageUrl), url: r.style.imageUrl }] : []));
+    return [...base, ...perRule.filter((img, i) => perRule.findIndex((x) => x.id === img.id) === i && !base.some((b) => b.id === img.id))];
+}
+/** Prefix for every source and style layer the engine owns, so basemap layers are never touched. */
+export const PREFIX = 'me';
+export const sourceId = (layerId) => `${PREFIX}:${layerId}`;
+export const OBJECT_ID_PROP = '__oid';
+export const LAYER_ID_PROP = '__lid';
+/** Marks the one label point an area gets in its own source (so a large area is labelled once, not once per tile). */
+export const LABEL_POINT_PROP = '__lp';
+const notLabelPoint = ['!=', ['get', LABEL_POINT_PROP], true];
+/** Area layers with a label carry a label point per object next to the shape. */
+export function needsLabelPoints(layer) {
+    return layer.visualization.type === 'polygon' && layer.visualization.label !== undefined;
+}
+/** Data-driven dashes (StyleTokens.dash), first matching rule wins; null when no rule asks for dashes. */
+export function dashExpression(rules) {
+    if (!(rules ?? []).some((r) => r.style.dash))
+        return null;
+    const solid = ['literal', [1, 0]];
+    const branches = [];
+    for (const rule of rules ?? []) {
+        if (rule.style.dash === undefined)
+            continue;
+        const value = ['literal', rule.style.dash];
+        if (rule.property === undefined)
+            return branches.length ? ['case', ...branches, value] : value;
+        const condition = ruleCondition(rule);
+        if (condition !== null)
+            branches.push(condition, value);
+    }
+    return ['case', ...branches, solid];
+}
+const BACKGROUND_ID = `${PREFIX}:background`;
+/** MapLibre style for the configured basemap. 'none' needs no network at all. */
+export function basemapStyle(basemap, theme) {
+    const background = { id: BACKGROUND_ID, type: 'background', paint: { 'background-color': basemap.background ?? theme.background } };
+    // Labels are rasterized in the browser from the app-supplied font file: no glyph server (MapLibre v6 font-faces).
+    const fonts = basemap.font ? { 'font-faces': { [LABEL_FONT]: basemap.font.url } } : {};
+    if (basemap.kind === 'style' && basemap.styleUrl)
+        return basemap.styleUrl;
+    if (basemap.kind === 'tiles' && basemap.tileUrl) {
+        return {
+            version: 8,
+            ...fonts,
+            sources: {
+                [`${PREFIX}:basemap`]: { type: 'raster', ...tilesOrUrl(basemap.tileUrl), tileSize: 256, ...(basemap.maxZoom !== undefined ? { maxzoom: basemap.maxZoom } : {}), ...(basemap.attribution ? { attribution: basemap.attribution } : {}) },
+            },
+            layers: [background, { id: `${PREFIX}:basemap`, type: 'raster', source: `${PREFIX}:basemap` }],
+        };
+    }
+    return { version: 8, ...fonts, sources: {}, layers: [background] };
+}
+/**
+ * A fetched street-map style with the engine's label font added (MapLibre v6 font-faces) and its relative URLs
+ * made absolute, so it can be passed as an object.
+ */
+export function withLabelFont(style, styleUrl, fontUrl) {
+    const base = styleUrl.slice(0, styleUrl.lastIndexOf('/') + 1);
+    // Not new URL(): it would percent-encode the {fontstack}/{range} placeholders.
+    const abs = (u) => (typeof u === 'string' && !/^[a-z][a-z0-9+.-]*:/i.test(u) ? (u.startsWith('/') ? new URL(styleUrl).origin + u : base + u) : u);
+    const sources = Object.fromEntries(Object.entries((style.sources ?? {})).map(([k, src]) => [
+        k,
+        { ...src, ...(src.url ? { url: abs(src.url) } : {}), ...(Array.isArray(src.tiles) ? { tiles: src.tiles.map(abs) } : {}), ...(typeof src.data === 'string' ? { data: abs(src.data) } : {}) },
+    ]));
+    const sprite = Array.isArray(style.sprite) ? style.sprite.map((s) => ({ ...s, url: abs(s.url) })) : abs(style.sprite);
+    return {
+        ...style,
+        ...(style.glyphs ? { glyphs: abs(style.glyphs) } : {}),
+        ...(style.sprite ? { sprite } : {}),
+        sources,
+        'font-faces': { ...(style['font-faces'] ?? {}), [LABEL_FONT]: fontUrl },
+    };
+}
+const isPrimitive = (v) => ['string', 'number', 'boolean'].includes(typeof v);
+/** Very large finite sentinels: a missing or non-numeric value never satisfies a numeric comparison. */
+const LOW = -1e300;
+const HIGH = 1e300;
+/** The MapLibre condition for one rule, or null when the rule cannot be expressed (it is then skipped). */
+export function ruleCondition(rule) {
+    if (rule.property === undefined)
+        return true;
+    const get = ['get', rule.property];
+    // A missing (or hidden, doc 28 G13) property must never match a comparison: MapLibre's to-number turns null into
+    // 0, so the fallback is put in first. Non-numbers fail the conversion and get the fallback too.
+    const num = (fallback) => ['to-number', ['coalesce', get, fallback], fallback];
+    const op = rule.op ?? 'eq';
+    const v = rule.value !== undefined ? rule.value : rule.equals;
+    switch (op) {
+        case 'eq':
+            return isPrimitive(v) ? ['==', get, v] : null;
+        case 'neq':
+            return isPrimitive(v) ? ['!=', get, v] : null;
+        case 'gt':
+            return typeof v === 'number' ? ['>', num(LOW), v] : null;
+        case 'gte':
+            return typeof v === 'number' ? ['>=', num(LOW), v] : null;
+        case 'lt':
+            return typeof v === 'number' ? ['<', num(HIGH), v] : null;
+        case 'lte':
+            return typeof v === 'number' ? ['<=', num(HIGH), v] : null;
+        case 'between':
+            return Array.isArray(v) && typeof v[0] === 'number' && typeof v[1] === 'number' ? ['all', ['>=', num(LOW), v[0]], ['<=', num(HIGH), v[1]]] : null;
+        case 'in':
+            return Array.isArray(v) && v.every(isPrimitive) ? ['in', ['to-string', get], ['literal', v.map(String)]] : null;
+    }
+}
+/**
+ * A data-driven expression for one style token: first matching rule wins (as the StyleRule contract says).
+ * Rules without `property` match everything and end the chain.
+ */
+const SCALABLE = new Set(['opacity', 'size', 'strokeWidth', 'color', 'strokeColor']);
+/** A token's expression: a continuous scale's per-object value (`$s:<token>`) first, then the rules. */
+export function tokenExpression(rules, key, fallback) {
+    const base = ruleExpression(rules, key, fallback);
+    return SCALABLE.has(key) ? ['coalesce', ['get', scaled(key)], base] : base;
+}
+function ruleExpression(rules, key, fallback) {
+    const branches = [];
+    for (const rule of rules ?? []) {
+        const value = rule.style[key];
+        if (value === undefined)
+            continue;
+        if (rule.property === undefined) {
+            return branches.length ? ['case', ...branches, value] : value;
+        }
+        const condition = ruleCondition(rule);
+        if (condition === null)
+            continue;
+        branches.push(condition, value);
+    }
+    return branches.length ? ['case', ...branches, fallback] : fallback;
+}
+/** Point markers stand up and keep their size when the camera tilts (3D views), instead of lying flat on the ground. */
+const UPRIGHT = { 'circle-pitch-alignment': 'viewport', 'circle-pitch-scale': 'viewport' };
+const state = (name) => ['boolean', ['feature-state', name], false];
+/** Wraps a base expression: selected wins, then hovered, then the data-driven value. */
+const interactive = (selected, hovered, base) => ['case', state('selected'), selected, state('hovered'), hovered, base];
+const withDash = (rules) => {
+    const dash = dashExpression(rules);
+    return dash === null ? {} : { 'line-dasharray': dash };
+};
+/** The text layer for a labelled engine layer, or none when there is no label or no label font. */
+function labelLayer(layer, theme, hasFont) {
+    const label = layer.visualization.label;
+    if (!label || !hasFont)
+        return [];
+    const line = layer.visualization.type === 'line';
+    const area = needsLabelPoints(layer);
+    return [
+        {
+            id: `${PREFIX}:${layer.id}:label`,
+            type: 'symbol',
+            source: sourceId(layer.id),
+            ...(area ? { filter: ['==', ['get', LABEL_POINT_PROP], true] } : {}),
+            ...(label.minZoom !== undefined ? { minzoom: label.minZoom } : {}),
+            layout: {
+                visibility: layer.visible ? 'visible' : 'none',
+                'text-field': ['to-string', ['get', label.property]],
+                'text-font': [LABEL_FONT],
+                'text-size': label.size ?? 12,
+                ...(line
+                    ? { 'symbol-placement': 'line' }
+                    : area
+                        ? label.placement === 'top'
+                            ? // Hangs below its point, just inside the top edge.
+                                { 'text-anchor': 'top', 'text-offset': [0, 0.2] }
+                            : // An area's one label moves to free space around its point rather than vanishing behind markers.
+                                { 'text-variable-anchor': ['center', 'top', 'bottom', 'left', 'right', 'top-left', 'top-right', 'bottom-left', 'bottom-right'], 'text-radial-offset': 0.8, 'text-justify': 'auto' }
+                        : { 'text-anchor': 'top', 'text-offset': [0, 0.9] }),
+                'text-optional': true,
+            },
+            paint: { 'text-color': label.color ?? theme.labelColor, 'text-halo-color': label.haloColor ?? theme.labelHalo, 'text-halo-width': 1.4 },
+        },
+    ];
+}
+/** The MapLibre style layers for one engine layer, bottom to top. Labels need a label font (`hasFont`). */
+export function styleLayersFor(layer, theme, hasFont = false) {
+    const shapes = shapeLayersFor(layer, theme, hasFont);
+    // No label for a layer this style cannot draw (a label without its shape would mislead).
+    return [...shapes, ...(layer.visualization.type === 'heatmap' || !shapes.length ? [] : labelLayer(layer, theme, hasFont))];
+}
+function shapeLayersFor(layer, theme, hasFont) {
+    // Heights and models are drawn by the deck.gl host (deck-host.ts), not by MapLibre style layers.
+    if (hostedByDeck(layer))
+        return [];
+    const src = sourceId(layer.id);
+    const rules = layer.visualization.style;
+    const visibility = layer.visible ? 'visible' : 'none';
+    const id = (part) => `${PREFIX}:${layer.id}:${part}`;
+    switch (layer.visualization.type) {
+        case 'marker': {
+            const size = tokenExpression(rules, 'size', 6);
+            const vz = layer.visualization;
+            // Clustered sources mix bubbles and points: point layers draw only unclustered features.
+            const unclustered = vz.cluster ? { filter: ['!', ['has', 'point_count']] } : {};
+            const clusters = vz.cluster
+                ? [
+                    {
+                        id: id('clusters'),
+                        type: 'circle',
+                        source: src,
+                        filter: ['has', 'point_count'],
+                        layout: { visibility },
+                        paint: {
+                            ...UPRIGHT,
+                            'circle-color': theme.clusterColor,
+                            'circle-opacity': 0.85,
+                            'circle-radius': ['step', ['get', 'point_count'], 13, 10, 17, 50, 22, 200, 28],
+                            'circle-stroke-color': theme.clusterRing,
+                            'circle-stroke-width': 2,
+                        },
+                    },
+                    ...(hasFont
+                        ? [
+                            {
+                                id: id('cluster-count'),
+                                type: 'symbol',
+                                source: src,
+                                filter: ['has', 'point_count'],
+                                layout: { visibility, 'text-field': ['get', 'point_count_abbreviated'], 'text-font': [LABEL_FONT], 'text-size': 12, 'text-allow-overlap': true },
+                                paint: { 'text-color': theme.clusterText },
+                            },
+                        ]
+                        : []),
+                ]
+                : [];
+            if (vz.icon) {
+                const icon = vz.icon;
+                const px = icon.size ?? 18;
+                const fallback = icon.shape ? shapeImageId(icon.shape) : icon.imageUrl ? urlImageId(icon.imageUrl) : '';
+                // First matching rule's image wins, like every other style token.
+                const imageRules = (rules ?? []).map((r) => (r.style.imageUrl ? { ...r, style: { ...r.style, imageUrl: urlImageId(r.style.imageUrl) } } : r));
+                const image = tokenExpression(imageRules, 'imageUrl', fallback);
+                return [
+                    ...clusters,
+                    {
+                        // Selection / hover halo under the icon (icons themselves cannot carry a stroke).
+                        id: id('halo'),
+                        type: 'circle',
+                        source: src,
+                        ...unclustered,
+                        layout: { visibility },
+                        paint: {
+                            ...UPRIGHT,
+                            'circle-radius': px / 2 + 6,
+                            'circle-color': interactive(theme.selectionColor, theme.hoverColor, theme.selectionColor),
+                            'circle-opacity': interactive(0.55, 0.3, 0),
+                        },
+                    },
+                    {
+                        id: id('icon'),
+                        type: 'symbol',
+                        source: src,
+                        ...unclustered,
+                        layout: {
+                            visibility,
+                            'icon-image': image,
+                            'icon-size': px / ICON_PIXELS,
+                            'icon-allow-overlap': true,
+                            'icon-ignore-placement': true,
+                            'icon-rotation-alignment': 'map',
+                            // Upright in a tilted 3D view (facing the camera), still turned by heading relative to north.
+                            'icon-pitch-alignment': 'viewport',
+                            ...(icon.rotateBy ? { 'icon-rotate': ['to-number', ['get', icon.rotateBy], 0] } : {}),
+                        },
+                        paint: {
+                            ...(icon.shape ? { 'icon-color': tokenExpression(rules, 'color', theme.markerColor), 'icon-halo-color': tokenExpression(rules, 'strokeColor', '#0B100E'), 'icon-halo-width': 1 } : {}),
+                            'icon-opacity': tokenExpression(rules, 'opacity', 1),
+                        },
+                    },
+                ];
+            }
+            return [
+                ...clusters,
+                {
+                    ...unclustered,
+                    id: id('circle'),
+                    type: 'circle',
+                    source: src,
+                    layout: { visibility },
+                    paint: {
+                        ...UPRIGHT,
+                        'circle-color': tokenExpression(rules, 'color', theme.markerColor),
+                        'circle-opacity': tokenExpression(rules, 'opacity', 1),
+                        'circle-radius': interactive(['+', size, 3], ['+', size, 2], size),
+                        'circle-stroke-color': interactive(theme.selectionColor, theme.hoverColor, tokenExpression(rules, 'strokeColor', '#0B100E')),
+                        'circle-stroke-width': interactive(3, 2, tokenExpression(rules, 'strokeWidth', 1.5)),
+                    },
+                },
+            ];
+        }
+        case 'track': {
+            const width = tokenExpression(rules, 'size', 2.5);
+            return [
+                {
+                    id: id('track'),
+                    type: 'line',
+                    source: src,
+                    layout: { visibility, 'line-join': 'round', 'line-cap': 'round' },
+                    paint: {
+                        'line-color': interactive(theme.selectionColor, theme.hoverColor, tokenExpression(rules, 'color', theme.trackColor)),
+                        'line-opacity': tokenExpression(rules, 'opacity', 0.7),
+                        'line-width': interactive(['+', width, 1.5], ['+', width, 1], width),
+                    },
+                },
+            ];
+        }
+        case 'line': {
+            const width = tokenExpression(rules, 'size', 2.5);
+            return [
+                {
+                    id: id('line'),
+                    type: 'line',
+                    source: src,
+                    layout: { visibility, 'line-join': 'round', 'line-cap': 'round' },
+                    paint: {
+                        'line-color': interactive(theme.selectionColor, theme.hoverColor, tokenExpression(rules, 'color', theme.lineColor)),
+                        'line-opacity': tokenExpression(rules, 'opacity', 0.9),
+                        'line-width': interactive(['+', width, 2.5], ['+', width, 1.5], width),
+                        ...withDash(rules),
+                    },
+                },
+            ];
+        }
+        case 'heatmap': {
+            const h = layer.visualization.heatmap ?? {};
+            const weight = h.weightProperty ? ['*', ['to-number', ['get', h.weightProperty], 0], h.weightScale ?? 1] : h.weightScale ?? 1;
+            return [
+                {
+                    id: id('heatmap'),
+                    type: 'heatmap',
+                    source: src,
+                    layout: { visibility },
+                    paint: {
+                        'heatmap-weight': weight,
+                        'heatmap-radius': h.radius ?? 24,
+                        'heatmap-intensity': h.intensity ?? 1,
+                        'heatmap-opacity': 0.85,
+                        'heatmap-color': ['interpolate', ['linear'], ['heatmap-density'], 0, 'rgba(0,0,0,0)', 0.2, theme.heatLow, 0.5, theme.heatMid, 0.8, theme.heatHigh, 1, theme.heatMax],
+                    },
+                },
+            ];
+        }
+        // Images are drawn by the renderer itself (one image source per object); link layers arrive as lines.
+        // The pictures themselves are image sources the renderer adds per object (under these layers). Here: a
+        // transparent fill so a picture can be clicked, and its outline when hovered or selected.
+        case 'image':
+            return [
+                { id: id('fill'), type: 'fill', source: src, layout: { visibility }, paint: { 'fill-color': '#000000', 'fill-opacity': 0 } },
+                { id: id('outline'), type: 'line', source: src, layout: { visibility }, paint: { 'line-color': interactive(theme.selectionColor, theme.hoverColor, '#000000'), 'line-width': interactive(3, 2, 0), 'line-opacity': interactive(1, 0.8, 0) } },
+            ];
+        // Link layers reach renderers as lines (the runtime's effective layer).
+        case 'link':
+            return [];
+        case 'extrusion': {
+            // MapLibre's own extrusions: they stand on terrain natively.
+            const x = layer.visualization.extrusion ?? {};
+            const height = x.heightProperty ? ['to-number', ['get', x.heightProperty], x.height ?? 0] : (x.height ?? 0);
+            const base = x.baseProperty ? ['to-number', ['get', x.baseProperty], x.base ?? 0] : (x.base ?? 0);
+            return [
+                {
+                    id: id('extrusion'),
+                    type: 'fill-extrusion',
+                    source: src,
+                    filter: notLabelPoint,
+                    layout: { visibility },
+                    paint: {
+                        'fill-extrusion-color': interactive(theme.selectionColor, theme.hoverColor, tokenExpression(rules, 'color', theme.fillColor)),
+                        'fill-extrusion-height': height,
+                        'fill-extrusion-base': base,
+                        // Not data-driven in MapLibre: one opacity per layer (the catch-all rule's, else 0.85).
+                        'fill-extrusion-opacity': (rules ?? []).find((r) => r.property === undefined && r.style.opacity !== undefined)?.style.opacity ?? 0.85,
+                    },
+                },
+            ];
+        }
+        case 'model':
+        case 'volume':
+            // Models are drawn by the deck.gl host; volumes come in phase 3E (the renderer reports the gap until then).
+            return [];
+        case 'polygon':
+            return [
+                {
+                    id: id('fill'),
+                    type: 'fill',
+                    source: src,
+                    filter: notLabelPoint,
+                    layout: { visibility },
+                    paint: {
+                        'fill-color': tokenExpression(rules, 'color', theme.fillColor),
+                        'fill-opacity': interactive(0.32, 0.26, tokenExpression(rules, 'opacity', 0.18)),
+                    },
+                },
+                {
+                    id: id('outline'),
+                    type: 'line',
+                    source: src,
+                    filter: notLabelPoint,
+                    layout: { visibility },
+                    paint: {
+                        'line-color': interactive(theme.selectionColor, theme.hoverColor, tokenExpression(rules, 'strokeColor', tokenExpression(rules, 'color', theme.fillColor))),
+                        'line-width': interactive(3, 2, tokenExpression(rules, 'strokeWidth', 1.5)),
+                        ...withDash(rules),
+                    },
+                },
+            ];
+    }
+}

package/vendor/map-engine/present/decorations.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Decorations: shapes the engine derives from a layer's objects and draws with it, in engine-owned layers next to
+ * it (doc 28 G2, G9, G12): position error areas, unresolved alternatives, range rings, camera footprints. They are
+ * plain polygons, lines and points, so every renderer draws them with what it already has. They follow their
+ * objects (rebuilt with each change of the layer), and a click on one selects the object it belongs to.
+ */
+import type { FootprintConfig, Geometry, MapLayer, Position, SpatialObject } from '../core/types.js';
+/** Engine layer ids are `__deco~<layerId>~<part>`; the part says what it draws. */
+export declare const DECO_PREFIX = "__deco~";
+declare const PARTS: readonly ["footprint", "uncertainty", "alt-lines", "alt-points", "rings"];
+type Part = (typeof PARTS)[number];
+export declare const decoLayerId: (layerId: string, part: Part) => string;
+/** The application layer and object a decoration belongs to (for picking), or null for any other layer. */
+export declare function decorationOwner(layerId: string, objectId: string): {
+    layerId: string;
+    objectId: string;
+} | null;
+/** The engine layers a layer's decorations need (none when it has no decoration options). */
+export declare function decorationLayers(layer: MapLayer): MapLayer[];
+export declare const formatDistance: (m: number) => string;
+/** The ground area a camera sees (FootprintConfig); null without a heading. */
+export declare function footprintOf(f: FootprintConfig, at: Position, props: Record<string, unknown> | undefined): Geometry | null;
+/** Decoration objects per engine layer, for a layer's (presented) objects. */
+export declare function decorationObjects(layer: MapLayer, objects: SpatialObject[]): Record<string, SpatialObject[]>;
+export {};