@faclon-labs/app-sdk 0.1.0 → 0.3.0

package/vendor/map-engine/layers/layers.d.ts

@@ -0,0 +1,49 @@
+import type { GeometryType, MapLayer, RendererCapabilities, SpatialObject, StyleRule, StyleTokens, VolumeConfig, SpatialQuery, TimeRange, ValidationResult, VisualizationType } from '../core/types.js';
+/** Which geometry each generic visualization draws. Objects of other types are left out of that layer's scene. */
+export declare const GEOMETRY_FOR: Record<VisualizationType, GeometryType>;
+/** Can this layer draw this object? Families, not exact types: a marker layer draws Point and MultiPoint. */
+export declare function drawable(layer: MapLayer, object: SpatialObject): boolean;
+/**
+ * Which geometry a visualization's SOURCE must have. Trails are drawn as lines but built from point histories; a
+ * link layer's source names the objects whose links it draws (usually points).
+ */
+export declare const SOURCE_GEOMETRY_FOR: Record<VisualizationType, GeometryType>;
+/** Layers whose objects do not come from object queries: trails (history) and links (the link provider). */
+export declare const DERIVED_TYPES: readonly VisualizationType[];
+export declare function validateLayer(value: unknown): ValidationResult;
+/** Holds layer definitions. It knows nothing about data sources or rendering. */
+export declare class LayerRegistry {
+    private readonly layers;
+    constructor(initial?: MapLayer[]);
+    add(layer: MapLayer): void;
+    update(id: string, patch: Partial<Omit<MapLayer, 'id'>>): MapLayer;
+    remove(id: string): void;
+    get(id: string): MapLayer | undefined;
+    has(id: string): boolean;
+    /** Layers sorted by zIndex, then id, so the order is deterministic. */
+    list(): MapLayer[];
+    visible(): MapLayer[];
+    private require;
+}
+/** What a layer needs from the renderer beyond flat 2D (ADR-026..028). */
+export declare function layerNeeds(layer: MapLayer): Array<keyof RendererCapabilities>;
+/** Provider hints the runtime adds to every layer query (doc §13): the zoom shown and, in replay, the time range. */
+export interface QueryHints {
+    zoom?: number;
+    time?: TimeRange;
+}
+/** The query a layer needs inside the current viewport bounds (ADR-013: the viewport is a data boundary). */
+export declare function layerQuery(layer: MapLayer, bounds?: SpatialQuery['bounds'], hints?: QueryHints): SpatialQuery;
+/** First matching rule's value for a style token (StyleRule contract), evaluated in JS — for renderers that style objects one by one. */
+export declare function tokenFor<K extends keyof StyleTokens>(rules: StyleRule[] | undefined, key: K, props: Record<string, unknown> | undefined, fallback: NonNullable<StyleTokens[K]>): NonNullable<StyleTokens[K]>;
+/** One object's coverage volume (phase 3E), from the layer's fixed values or the object's properties. */
+export interface ResolvedVolume {
+    shape: 'dome' | 'wedge';
+    range: number;
+    azimuth: number;
+    beamWidth: number;
+    minElevation: number;
+    maxElevation: number;
+}
+/** Resolves a layer's volume settings for one object; null when it has no usable range. */
+export declare function volumeOf(v: VolumeConfig | undefined, props: Record<string, unknown> | undefined): ResolvedVolume | null;

package/vendor/map-engine/layers/layers.js

@@ -0,0 +1,316 @@
+import { MapEngineError } from '../core/errors.js';
+import { geometryFamily } from '../core/geometry-family.js';
+import { validateGeometry, validatePosition } from '../spatial/geometry.js';
+import { matchesCondition, validateConditions } from '../spatial/query.js';
+import { scaled, validatePresentation } from '../present/present.js';
+const VISUALIZATIONS = ['marker', 'line', 'polygon', 'heatmap', 'track', 'extrusion', 'model', 'volume', 'link', 'image'];
+/** Which geometry each generic visualization draws. Objects of other types are left out of that layer's scene. */
+export const GEOMETRY_FOR = { marker: 'Point', line: 'LineString', polygon: 'Polygon', heatmap: 'Point', track: 'LineString', extrusion: 'Polygon', model: 'Point', volume: 'Point', link: 'LineString', image: 'Polygon' };
+/** Can this layer draw this object? Families, not exact types: a marker layer draws Point and MultiPoint. */
+export function drawable(layer, object) {
+    return geometryFamily(GEOMETRY_FOR[layer.visualization.type]) === geometryFamily(object.geometry.type);
+}
+/**
+ * Which geometry a visualization's SOURCE must have. Trails are drawn as lines but built from point histories; a
+ * link layer's source names the objects whose links it draws (usually points).
+ */
+export const SOURCE_GEOMETRY_FOR = { ...GEOMETRY_FOR, track: 'Point', link: 'Point' };
+/** Layers whose objects do not come from object queries: trails (history) and links (the link provider). */
+export const DERIVED_TYPES = ['track', 'link'];
+export function validateLayer(value) {
+    if (typeof value !== 'object' || value === null)
+        return { valid: false, reason: 'layer is not an object' };
+    const l = value;
+    if (typeof l.id !== 'string' || l.id.trim() === '')
+        return { valid: false, reason: 'layer.id must be a non-empty string' };
+    if (l.id.includes(':'))
+        return { valid: false, reason: `layer.id "${l.id}" must not contain ":" (used in scene keys)` };
+    if (l.id.includes('~') || l.id.startsWith('__'))
+        return { valid: false, reason: `layer.id "${l.id}" must not contain "~" or start with "__" (used by engine layers)` };
+    if (typeof l.visible !== 'boolean')
+        return { valid: false, reason: `layer ${l.id}: visible must be a boolean` };
+    if (typeof l.zIndex !== 'number' || !Number.isFinite(l.zIndex))
+        return { valid: false, reason: `layer ${l.id}: zIndex must be a finite number` };
+    if (!l.visualization || !VISUALIZATIONS.includes(l.visualization.type)) {
+        return { valid: false, reason: `layer ${l.id}: visualization.type must be one of ${VISUALIZATIONS.join(', ')}` };
+    }
+    const s = l.source;
+    if (!s || typeof s !== 'object')
+        return { valid: false, reason: `layer ${l.id}: source is required` };
+    // An empty source would mean "load everything", which the performance model forbids.
+    if (s.ontologyType === undefined && s.objectIds === undefined && s.spatialQuery === undefined && s.filter === undefined && s.where === undefined) {
+        return { valid: false, reason: `layer ${l.id}: source needs at least one of ontologyType, objectIds, spatialQuery, filter, where` };
+    }
+    if (s.where !== undefined) {
+        const w = validateConditions(s.where, `layer ${l.id}: source.where`);
+        if (!w.valid)
+            return w;
+    }
+    if (s.spatialQuery) {
+        const q = s.spatialQuery;
+        if (q.relation === 'near') {
+            const p = validatePosition(q.position, `layer ${l.id} near.position`);
+            if (!p.valid)
+                return p;
+            if (!(q.distanceMeters >= 0))
+                return { valid: false, reason: `layer ${l.id}: near.distanceMeters must be >= 0` };
+        }
+        else if (q.relation === 'nearest') {
+            const p = validatePosition(q.position, `layer ${l.id} nearest.position`);
+            if (!p.valid)
+                return p;
+            if (!(Number.isInteger(q.count) && q.count >= 1))
+                return { valid: false, reason: `layer ${l.id}: nearest.count must be a whole number >= 1` };
+        }
+        else if (q.relation !== 'bbox') {
+            const g = validateGeometry(q.geometry);
+            if (!g.valid)
+                return { valid: false, reason: `layer ${l.id}: ${g.reason}` };
+        }
+    }
+    for (const [i, rule] of (l.visualization.style ?? []).entries()) {
+        const op = rule.op ?? 'eq';
+        if (!RULE_OPS.includes(op))
+            return { valid: false, reason: `layer ${l.id}: style[${i}].op "${String(op)}" is not one of ${RULE_OPS.join(', ')}` };
+        const v = rule.value ?? rule.equals;
+        if (rule.property !== undefined && op === 'between' && !(Array.isArray(v) && v.length === 2 && v.every((n) => typeof n === 'number'))) {
+            return { valid: false, reason: `layer ${l.id}: style[${i}] "between" needs value [min, max]` };
+        }
+        if (rule.property !== undefined && op === 'in' && !Array.isArray(v))
+            return { valid: false, reason: `layer ${l.id}: style[${i}] "in" needs an array value` };
+        const dash = rule.style?.dash;
+        if (dash !== undefined && !(Array.isArray(dash) && dash.length >= 2 && dash.every((n) => typeof n === 'number' && n >= 0) && dash.some((n) => n > 0))) {
+            return { valid: false, reason: `layer ${l.id}: style[${i}].dash must be at least two non-negative numbers, e.g. [2, 2]` };
+        }
+        if (rule.property !== undefined && ['gt', 'gte', 'lt', 'lte'].includes(op) && typeof v !== 'number') {
+            return { valid: false, reason: `layer ${l.id}: style[${i}] "${op}" needs a number value` };
+        }
+    }
+    const vz = l.visualization;
+    const SHAPES = ['circle', 'square', 'triangle', 'diamond', 'arrow'];
+    if ((vz.icon || vz.cluster) && vz.type !== 'marker')
+        return { valid: false, reason: `layer ${l.id}: icon and cluster apply to marker layers only` };
+    if (vz.heatmap && vz.type !== 'heatmap')
+        return { valid: false, reason: `layer ${l.id}: heatmap options need visualization.type "heatmap"` };
+    if (vz.track && vz.type !== 'track')
+        return { valid: false, reason: `layer ${l.id}: track options need visualization.type "track"` };
+    if (vz.track?.windowMinutes !== undefined && !(vz.track.windowMinutes > 0))
+        return { valid: false, reason: `layer ${l.id}: track.windowMinutes must be > 0` };
+    if (vz.icon) {
+        if (vz.icon.shape !== undefined && !SHAPES.includes(vz.icon.shape))
+            return { valid: false, reason: `layer ${l.id}: icon.shape must be one of ${SHAPES.join(', ')}` };
+        const ruleImages = (vz.style ?? []).some((r) => typeof r.style?.imageUrl === 'string');
+        if (vz.icon.shape === undefined && !vz.icon.imageUrl && !ruleImages)
+            return { valid: false, reason: `layer ${l.id}: icon needs a shape, an imageUrl, or images on its style rules` };
+        if (vz.icon.size !== undefined && !(vz.icon.size > 0))
+            return { valid: false, reason: `layer ${l.id}: icon.size must be > 0` };
+    }
+    if (vz.cluster) {
+        const { radius, maxZoom } = vz.cluster;
+        if ((radius !== undefined && !(radius > 0)) || (maxZoom !== undefined && !(maxZoom >= 0 && maxZoom <= 24)))
+            return { valid: false, reason: `layer ${l.id}: cluster.radius must be > 0 and maxZoom within [0, 24]` };
+    }
+    const v3 = validate3d(l);
+    if (!v3.valid)
+        return v3;
+    const vp = validatePresentation(l);
+    if (!vp.valid)
+        return vp;
+    const label = l.visualization.label;
+    if (label !== undefined && (typeof label.property !== 'string' || label.property === ''))
+        return { valid: false, reason: `layer ${l.id}: label.property is required` };
+    if (label?.placement !== undefined && !['center', 'top'].includes(label.placement))
+        return { valid: false, reason: `layer ${l.id}: label.placement must be center or top` };
+    return { valid: true };
+}
+const RULE_OPS = ['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'between', 'in'];
+const REFERENCES = ['msl', 'agl', 'ellipsoid'];
+const ELEVATED = ['marker', 'line', 'track', 'model', 'volume'];
+const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+const isName = (v) => typeof v === 'string' && v !== '';
+/** The 3D options of a layer (ADR-026..028): each on the visualizations it belongs to, with what it needs. */
+function validate3d(l) {
+    const vz = l.visualization;
+    const bad = (reason) => ({ valid: false, reason: `layer ${l.id}: ${reason}` });
+    const e = vz.elevation;
+    if (e) {
+        if (!ELEVATED.includes(vz.type))
+            return bad(`elevation applies to ${ELEVATED.join(', ')} layers`);
+        if (e.from !== 'geometry' && e.from !== 'property')
+            return bad(`elevation.from must be geometry or property`);
+        if (e.from === 'property' && !isName(e.property))
+            return bad(`elevation.property is required with from: property`);
+        // ADR-028: the reference is never guessed.
+        if (!REFERENCES.includes(e.reference))
+            return bad(`elevation.reference must be one of ${REFERENCES.join(', ')} (it is never guessed)`);
+        if (e.exaggeration !== undefined && !(isNum(e.exaggeration) && e.exaggeration > 0))
+            return bad(`elevation.exaggeration must be > 0`);
+    }
+    if (vz.extrusion && vz.type !== 'extrusion')
+        return bad(`extrusion options need visualization.type "extrusion"`);
+    if (vz.type === 'extrusion') {
+        const x = vz.extrusion ?? {};
+        if (!isNum(x.height) && !isName(x.heightProperty))
+            return bad(`extrusion needs a height or a heightProperty`);
+        if (x.height !== undefined && !(isNum(x.height) && x.height >= 0))
+            return bad(`extrusion.height must be >= 0`);
+        if (x.base !== undefined && !(isNum(x.base) && x.base >= 0))
+            return bad(`extrusion.base must be >= 0`);
+    }
+    if (vz.model && vz.type !== 'model')
+        return bad(`model options need visualization.type "model"`);
+    if (vz.type === 'model') {
+        const ruleModels = (vz.style ?? []).some((r) => isName(r.style?.modelUrl));
+        if (!isName(vz.model?.url) && !ruleModels)
+            return bad(`a model layer needs model.url or models on its style rules (style.modelUrl)`);
+        if (vz.model?.sizeMeters !== undefined && !(isNum(vz.model.sizeMeters) && vz.model.sizeMeters > 0))
+            return bad(`model.sizeMeters must be > 0`);
+    }
+    if (vz.volume && vz.type !== 'volume')
+        return bad(`volume options need visualization.type "volume"`);
+    if (vz.type === 'volume') {
+        const v = vz.volume;
+        if (!v || (v.shape !== 'dome' && v.shape !== 'wedge'))
+            return bad(`volume.shape must be dome or wedge`);
+        if (!(isNum(v.range) && v.range > 0) && !isName(v.rangeProperty))
+            return bad(`volume needs a range (> 0) or a rangeProperty`);
+        if (v.shape === 'wedge') {
+            if (!isNum(v.azimuth) && !isName(v.azimuthProperty))
+                return bad(`a wedge needs an azimuth or azimuthProperty`);
+            if (!(isNum(v.beamWidth) && v.beamWidth > 0 && v.beamWidth <= 360) && !isName(v.beamWidthProperty))
+                return bad(`a wedge needs a beamWidth in (0, 360] or a beamWidthProperty`);
+        }
+        const lo = v.minElevation ?? 0;
+        const hi = v.maxElevation ?? 90;
+        if (!(isNum(lo) && isNum(hi) && lo >= -90 && hi <= 90 && lo < hi))
+            return bad(`volume elevations must satisfy -90 <= min < max <= 90`);
+    }
+    return { valid: true };
+}
+/** Holds layer definitions. It knows nothing about data sources or rendering. */
+export class LayerRegistry {
+    layers = new Map();
+    constructor(initial = []) {
+        for (const l of initial)
+            this.add(l);
+    }
+    add(layer) {
+        const v = validateLayer(layer);
+        if (!v.valid)
+            throw new MapEngineError('INVALID_LAYER', v.reason, { layerId: layer?.id });
+        if (this.layers.has(layer.id))
+            throw new MapEngineError('DUPLICATE_LAYER', `layer ${layer.id} already exists`, { layerId: layer.id });
+        this.layers.set(layer.id, structuredClone(layer));
+    }
+    update(id, patch) {
+        const current = this.require(id);
+        const next = { ...current, ...patch, id };
+        const v = validateLayer(next);
+        if (!v.valid)
+            throw new MapEngineError('INVALID_LAYER', v.reason, { layerId: id });
+        this.layers.set(id, structuredClone(next));
+        return this.get(id);
+    }
+    remove(id) {
+        this.require(id);
+        this.layers.delete(id);
+    }
+    get(id) {
+        const l = this.layers.get(id);
+        return l ? structuredClone(l) : undefined;
+    }
+    has(id) {
+        return this.layers.has(id);
+    }
+    /** Layers sorted by zIndex, then id, so the order is deterministic. */
+    list() {
+        return [...this.layers.values()].sort((a, b) => a.zIndex - b.zIndex || a.id.localeCompare(b.id)).map((l) => structuredClone(l));
+    }
+    visible() {
+        return this.list().filter((l) => l.visible);
+    }
+    require(id) {
+        const l = this.layers.get(id);
+        if (!l)
+            throw new MapEngineError('UNKNOWN_LAYER', `layer ${id} does not exist`, { layerId: id });
+        return l;
+    }
+}
+/** What a layer needs from the renderer beyond flat 2D (ADR-026..028). */
+export function layerNeeds(layer) {
+    const needs = [];
+    const t = layer.visualization.type;
+    if (t === 'extrusion')
+        needs.push('extrusion');
+    if (t === 'model')
+        needs.push('models');
+    if (t === 'volume')
+        needs.push('volumes');
+    if (layer.visualization.elevation)
+        needs.push('altitude');
+    return needs;
+}
+/** The query a layer needs inside the current viewport bounds (ADR-013: the viewport is a data boundary). */
+export function layerQuery(layer, bounds, hints) {
+    const q = { geometryType: GEOMETRY_FOR[layer.visualization.type] };
+    if (layer.source.ontologyType !== undefined)
+        q.ontologyType = layer.source.ontologyType;
+    if (layer.source.objectIds !== undefined)
+        q.objectIds = [...layer.source.objectIds];
+    if (layer.source.spatialQuery !== undefined)
+        q.spatial = structuredClone(layer.source.spatialQuery);
+    if (layer.source.filter !== undefined)
+        q.filter = structuredClone(layer.source.filter);
+    if (layer.source.where !== undefined)
+        q.where = structuredClone(layer.source.where);
+    if (bounds)
+        q.bounds = { ...bounds };
+    // Rounded, so a provider that caches by query is not defeated by tiny camera moves.
+    if (hints?.zoom !== undefined)
+        q.zoom = Math.round(hints.zoom * 100) / 100;
+    if (hints?.time)
+        q.time = { ...hints.time };
+    return q;
+}
+/** First matching rule's value for a style token (StyleRule contract), evaluated in JS — for renderers that style objects one by one. */
+export function tokenFor(rules, key, props, fallback) {
+    // A continuous scale's value (set per object by the runtime) wins over every rule.
+    const own = props?.[scaled(key)];
+    if (own !== undefined && own !== null)
+        return own;
+    for (const r of rules ?? []) {
+        const v = r.style[key];
+        if (v === undefined)
+            continue;
+        if (r.property === undefined)
+            return v;
+        if (matchesCondition(props?.[r.property], { property: r.property, op: r.op ?? 'eq', value: r.value !== undefined ? r.value : r.equals }))
+            return v;
+    }
+    return fallback;
+}
+/** Resolves a layer's volume settings for one object; null when it has no usable range. */
+export function volumeOf(v, props) {
+    if (!v)
+        return null;
+    const read = (fixed, prop) => {
+        if (prop !== undefined) {
+            const raw = props?.[prop];
+            const n = typeof raw === 'number' ? raw : typeof raw === 'string' && raw.trim() !== '' ? Number(raw) : Number.NaN;
+            if (Number.isFinite(n))
+                return n;
+        }
+        return fixed;
+    };
+    const range = read(v.range, v.rangeProperty);
+    if (!(range !== undefined && range > 0))
+        return null;
+    return {
+        shape: v.shape,
+        range,
+        azimuth: read(v.azimuth, v.azimuthProperty) ?? 0,
+        beamWidth: v.shape === 'wedge' ? Math.max(1, Math.min(360, read(v.beamWidth, v.beamWidthProperty) ?? 60)) : 360,
+        minElevation: v.minElevation ?? 0,
+        maxElevation: v.maxElevation ?? 90,
+    };
+}

package/vendor/map-engine/maplibre/deck-host.d.ts

@@ -0,0 +1,105 @@
+/**
+ * deck.gl inside the MapLibre map (ADR-027, phase 3C): the engine layers MapLibre cannot draw — points and lines at
+ * their real height (with stems and ground shadows) and 3D models — rendered by deck.gl in the same WebGL context,
+ * interleaved with MapLibre's layers and terrain. Loaded only when a map has such a layer.
+ *
+ * Heights follow ADR-028: the layer states the reference; heights scale with the terrain's exaggeration so an
+ * aircraft keeps its true relation to the (exaggerated) mountains; `agl` stands on the ground under the object.
+ * No deck.gl type crosses into the engine: the renderer talks to this host, the host to deck.gl.
+ */
+import type { MapLayer, SceneObject } from '../core/types.js';
+import type { RendererTheme } from './style.js';
+type LayerCtor = new (props: Record<string, unknown>) => unknown;
+/** The slice of deck.gl the host uses (tests inject a fake; WebGL is not available in jsdom). */
+export interface DeckModules {
+    MapboxOverlay: new (props: {
+        interleaved: boolean;
+        layers: unknown[];
+    }) => DeckOverlayLike;
+    ScatterplotLayer: LayerCtor;
+    IconLayer: LayerCtor;
+    PathLayer: LayerCtor;
+    LineLayer: LayerCtor;
+    TextLayer: LayerCtor;
+    ScenegraphLayer: LayerCtor;
+    SimpleMeshLayer: LayerCtor;
+}
+export interface DeckOverlayLike {
+    setProps(props: {
+        layers: unknown[];
+    }): void;
+    pickObject(params: {
+        x: number;
+        y: number;
+        radius?: number;
+    }): {
+        object?: unknown;
+    } | null;
+    finalize(): void;
+}
+/** What the host needs from the map it lives in. */
+export interface DeckHostEnv {
+    addControl(overlay: DeckOverlayLike): void;
+    removeControl(overlay: DeckOverlayLike): void;
+    theme: RendererTheme;
+    /** The label font's family (labels at height are drawn by deck.gl); none = no labels. */
+    font(): string | undefined;
+    /** The terrain's exaggeration (1 without terrain). */
+    terrainExaggeration(): number;
+    /** Ground height (already exaggerated, as the map draws it) under a point; 0 when unknown or flat. */
+    ground(lng: number, lat: number): number;
+    warn(error: Error): void;
+}
+/** Default loader: the real deck.gl, split into its own chunks so 2D maps never download it. */
+export declare function loadDeck(): Promise<DeckModules>;
+/**
+ * Version shim (MapLibre v6 × deck.gl 9.4): deck.gl's interleaved mode reads MapLibre's private `map.transform`
+ * (height, elevation, _nearZ, _farZ). MapLibre v6 moved the transform under `map._camera` and renamed the planes
+ * to nearZ/farZ. When `map.transform` is missing, define a read-only view onto the v6 transform. Delete this once
+ * deck.gl supports MapLibre v6 natively.
+ */
+export declare function shimTransformForDeck(map: object): void;
+/** Layers this host draws instead of MapLibre: anything at a height, and models. */
+export declare function hostedByDeck(layer: MapLayer): boolean;
+export declare class DeckHost {
+    private readonly env;
+    private readonly load;
+    private modules;
+    private overlay;
+    private loading;
+    private destroyed;
+    private readonly hosted;
+    private warnedEllipsoid;
+    /** Longest side of each model file, in its own units, once loaded (sizes models in metres and pixels). */
+    private readonly extents;
+    /**
+     * Placed points per layer, keyed by the scene object: the renderer replaces only objects that changed, so a
+     * frame recomputes heights for those alone. Cleared when the layer definition or the ground changes.
+     */
+    private placed;
+    /** Ground heights by position (terrain lookups are not free); cleared when terrain tiles arrive. */
+    private groundCache;
+    constructor(env: DeckHostEnv, load?: () => Promise<DeckModules>);
+    /** Sets (or replaces) what one engine layer shows. */
+    setLayer(layer: MapLayer, objects: SceneObject[]): void;
+    removeLayer(id: string): void;
+    has(id: string): boolean;
+    /** Heights depend on the ground: recompute after terrain loads or changes. */
+    refresh(): void;
+    /** The top object under a screen point among deck.gl-drawn layers. */
+    pick(x: number, y: number, radius: number): {
+        objectId: string;
+        layerId: string;
+    } | null;
+    destroy(): void;
+    private render;
+    private readonly meshes;
+    private meshFor;
+    /** Height of an object in the map's metres (ADR-028), and the ground under it. */
+    private place;
+    private altitudeOf;
+    private points;
+    private paths;
+    private deckLayers;
+}
+export {};