@faclon-labs/app-sdk 0.1.0 → 0.3.0

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

@@ -0,0 +1,28 @@
+/** Interaction state keyed by stable objectId (ADR-009). Knows nothing about layers, data or rendering. */
+export class SelectionState {
+    now;
+    current;
+    constructor(now = Date.now) {
+        this.now = now;
+        this.current = { objectIds: [], source: 'init', timestamp: now() };
+    }
+    get() {
+        return { ...this.current, objectIds: [...this.current.objectIds] };
+    }
+    isSelected(objectId) {
+        return this.current.objectIds.includes(objectId);
+    }
+    /** Returns true when the selected ids changed. */
+    set(objectIds, source, primaryObjectId) {
+        const ids = [...new Set(objectIds)];
+        const primary = ids.length ? (primaryObjectId && ids.includes(primaryObjectId) ? primaryObjectId : ids[0]) : undefined;
+        const same = ids.length === this.current.objectIds.length && ids.every((id, i) => id === this.current.objectIds[i]) && primary === this.current.primaryObjectId;
+        if (same)
+            return false;
+        this.current = { objectIds: ids, source, timestamp: this.now(), ...(primary !== undefined ? { primaryObjectId: primary } : {}) };
+        return true;
+    }
+    clear(source) {
+        return this.set([], source);
+    }
+}

package/vendor/map-engine/spatial/geojson.d.ts

@@ -0,0 +1,15 @@
+import type * as GeoJSON from 'geojson';
+import type { Geometry, Position } from '../core/types.js';
+/** Steps used when a circle has to become a polygon (rendering, GeoJSON export). */
+export declare const CIRCLE_STEPS = 64;
+export declare function toGeoJSON(geometry: Geometry): GeoJSON.Geometry;
+/** Converts and validates. Throws MapEngineError('INVALID_GEOMETRY') on anything the model cannot hold. */
+export declare function fromGeoJSON(value: GeoJSON.Geometry): Geometry;
+/** `[longitude, latitude]`, the order renderer libraries expect for a center or a point. */
+export declare function toLngLat(p: Position): [number, number];
+/** From a renderer's `{ lng, lat }` object. */
+export declare function fromLngLat(v: {
+    lng: number;
+    lat: number;
+}): Position;
+export declare function toFeature(geometry: Geometry, properties?: GeoJSON.GeoJsonProperties): GeoJSON.Feature;

package/vendor/map-engine/spatial/geojson.js

@@ -0,0 +1,83 @@
+/**
+ * The GeoJSON boundary (ADR-006). This is the ONLY module that knows GeoJSON's
+ * `[longitude, latitude]` order. Everything else uses semantic Positions.
+ */
+import { circle as turfCircle } from '@turf/circle';
+import { MapEngineError } from '../core/errors.js';
+import { validateGeometry } from './geometry.js';
+/** Altitude is GeoJSON's third coordinate (ADR-028). */
+const toPair = (p) => (p.altitude === undefined ? [p.longitude, p.latitude] : [p.longitude, p.latitude, p.altitude]);
+function fromPair(pair, where) {
+    if (!Array.isArray(pair) || pair.length < 2)
+        throw new MapEngineError('INVALID_GEOMETRY', `${where} is not a [longitude, latitude] pair`);
+    const p = { longitude: pair[0], latitude: pair[1] };
+    if (pair.length > 2 && pair[2] !== null && pair[2] !== undefined)
+        p.altitude = pair[2];
+    return p;
+}
+/** Steps used when a circle has to become a polygon (rendering, GeoJSON export). */
+export const CIRCLE_STEPS = 64;
+export function toGeoJSON(geometry) {
+    switch (geometry.type) {
+        case 'Point':
+            return { type: 'Point', coordinates: toPair(geometry.coordinates) };
+        case 'LineString':
+            return { type: 'LineString', coordinates: geometry.coordinates.map(toPair) };
+        case 'Polygon':
+            return { type: 'Polygon', coordinates: geometry.coordinates.map((ring) => ring.map(toPair)) };
+        case 'MultiPoint':
+            return { type: 'MultiPoint', coordinates: geometry.coordinates.map(toPair) };
+        case 'MultiLineString':
+            return { type: 'MultiLineString', coordinates: geometry.coordinates.map((line) => line.map(toPair)) };
+        case 'MultiPolygon':
+            return { type: 'MultiPolygon', coordinates: geometry.coordinates.map((poly) => poly.map((ring) => ring.map(toPair))) };
+        case 'Circle':
+            return turfCircle(toPair(geometry.center), geometry.radiusMeters, { steps: CIRCLE_STEPS, units: 'meters' }).geometry;
+    }
+}
+const pairs = (list, where) => {
+    if (!Array.isArray(list))
+        throw new MapEngineError('INVALID_GEOMETRY', `${where} is not an array`);
+    return list.map((p, i) => fromPair(p, `${where}[${i}]`));
+};
+/** Converts and validates. Throws MapEngineError('INVALID_GEOMETRY') on anything the model cannot hold. */
+export function fromGeoJSON(value) {
+    let geometry;
+    switch (value.type) {
+        case 'Point':
+            geometry = { type: 'Point', coordinates: fromPair(value.coordinates, 'Point.coordinates') };
+            break;
+        case 'LineString':
+            geometry = { type: 'LineString', coordinates: pairs(value.coordinates, 'LineString.coordinates') };
+            break;
+        case 'Polygon':
+            geometry = { type: 'Polygon', coordinates: value.coordinates.map((ring, r) => pairs(ring, `Polygon.coordinates[${r}]`)) };
+            break;
+        case 'MultiPoint':
+            geometry = { type: 'MultiPoint', coordinates: pairs(value.coordinates, 'MultiPoint.coordinates') };
+            break;
+        case 'MultiLineString':
+            geometry = { type: 'MultiLineString', coordinates: value.coordinates.map((line, i) => pairs(line, `MultiLineString.coordinates[${i}]`)) };
+            break;
+        case 'MultiPolygon':
+            geometry = { type: 'MultiPolygon', coordinates: value.coordinates.map((poly, i) => poly.map((ring, r) => pairs(ring, `MultiPolygon.coordinates[${i}][${r}]`))) };
+            break;
+        default:
+            throw new MapEngineError('INVALID_GEOMETRY', `GeoJSON ${value.type} is not supported (Point, LineString, Polygon and their Multi forms)`);
+    }
+    const check = validateGeometry(geometry);
+    if (!check.valid)
+        throw new MapEngineError('INVALID_GEOMETRY', check.reason);
+    return geometry;
+}
+/** `[longitude, latitude]`, the order renderer libraries expect for a center or a point. */
+export function toLngLat(p) {
+    return [p.longitude, p.latitude];
+}
+/** From a renderer's `{ lng, lat }` object. */
+export function fromLngLat(v) {
+    return { latitude: v.lat, longitude: v.lng };
+}
+export function toFeature(geometry, properties = {}) {
+    return { type: 'Feature', geometry: toGeoJSON(geometry), properties };
+}

package/vendor/map-engine/spatial/geometry.d.ts

@@ -0,0 +1,13 @@
+import type { BoundingBox, Geometry, Position, ValidationResult } from '../core/types.js';
+export declare function validatePosition(value: unknown, where?: string): ValidationResult;
+/** Validates untrusted geometry (for example, from a provider). Never throws. */
+export declare function validateGeometry(value: unknown): ValidationResult;
+export { geometryFamily } from '../core/geometry-family.js';
+/** The positions that bound a geometry (a circle contributes its four extreme points). */
+export declare function positionsOf(geometry: Geometry): Position[];
+export declare function geometryBounds(geometry: Geometry): BoundingBox;
+/** Smallest bounds containing all inputs; undefined for an empty list. */
+export declare function unionBounds(list: BoundingBox[]): BoundingBox | undefined;
+export declare function boundsIntersect(a: BoundingBox, b: BoundingBox): boolean;
+export declare function boundsContainPosition(b: BoundingBox, p: Position): boolean;
+export declare function boundsToPolygon(b: BoundingBox): Geometry;

package/vendor/map-engine/spatial/geometry.js

@@ -0,0 +1,206 @@
+import { kinks } from '@turf/kinks';
+import { fromGeoJSON, toGeoJSON } from './geojson.js';
+const invalid = (reason) => ({ valid: false, reason });
+export function validatePosition(value, where = 'position') {
+    if (typeof value !== 'object' || value === null)
+        return invalid(`${where} is not an object`);
+    const { latitude, longitude } = value;
+    if (typeof latitude !== 'number' || !Number.isFinite(latitude))
+        return invalid(`${where}.latitude is not a finite number`);
+    if (typeof longitude !== 'number' || !Number.isFinite(longitude))
+        return invalid(`${where}.longitude is not a finite number`);
+    if (latitude < -90 || latitude > 90)
+        return invalid(`${where}.latitude ${latitude} is outside [-90, 90]`);
+    if (longitude < -180 || longitude > 180)
+        return invalid(`${where}.longitude ${longitude} is outside [-180, 180]`);
+    const { altitude } = value;
+    if (altitude !== undefined) {
+        if (typeof altitude !== 'number' || !Number.isFinite(altitude))
+            return invalid(`${where}.altitude is not a finite number of metres`);
+        // Below the deepest ocean floor or beyond geostationary orbit by far: a unit or parsing error, not a height.
+        if (altitude < -12_000 || altitude > 100_000_000)
+            return invalid(`${where}.altitude ${altitude} m is not a plausible height`);
+    }
+    return { valid: true };
+}
+const samePosition = (a, b) => a.latitude === b.latitude && a.longitude === b.longitude;
+function validateLine(coords, where) {
+    if (!Array.isArray(coords))
+        return invalid(`${where} is not an array`);
+    if (coords.length < 2)
+        return invalid(`${where} needs at least 2 positions`);
+    for (let i = 0; i < coords.length; i++) {
+        const r = validatePosition(coords[i], `${where}[${i}]`);
+        if (!r.valid)
+            return r;
+    }
+    return { valid: true };
+}
+function validateRings(rings, where) {
+    if (!Array.isArray(rings) || rings.length === 0)
+        return invalid(`${where} needs at least one ring`);
+    for (let r = 0; r < rings.length; r++) {
+        const ring = rings[r];
+        if (!Array.isArray(ring))
+            return invalid(`${where} ring ${r} is not an array`);
+        if (ring.length < 4)
+            return invalid(`${where} ring ${r} needs at least 4 positions (closed)`);
+        for (let i = 0; i < ring.length; i++) {
+            const p = validatePosition(ring[i], `${where}[${r}][${i}]`);
+            if (!p.valid)
+                return p;
+        }
+        if (!samePosition(ring[0], ring[ring.length - 1]))
+            return invalid(`${where} ring ${r} is not closed`);
+    }
+    const crossing = selfIntersection(rings);
+    if (crossing)
+        return invalid(`${where} edges cross each other near ${crossing.latitude.toFixed(6)}, ${crossing.longitude.toFixed(6)} (self-intersecting)`);
+    return { valid: true };
+}
+/**
+ * Where a polygon's edges cross (one ring crossing itself, or rings crossing each other), or null (doc §64).
+ * Turf's check is quadratic, so results are remembered by a fingerprint of the coordinates: a large polygon that
+ * arrives on every load is checked once.
+ */
+const crossings = new Map();
+const CROSSINGS_KEPT = 5000;
+function selfIntersection(rings) {
+    let h1 = 0x811c9dc5;
+    let h2 = 0;
+    let n = 0;
+    for (const ring of rings) {
+        for (const p of ring) {
+            const x = Math.round(p.longitude * 1e7);
+            const y = Math.round(p.latitude * 1e7);
+            h1 = Math.imul(h1 ^ x, 0x9e3779b1);
+            h1 = Math.imul(h1 ^ y, 0x85ebca6b);
+            h2 = (h2 * 31 + x * 7 + y * 13) % 0x1fffffffffffff;
+            n++;
+        }
+        h1 = Math.imul(h1 ^ -1, 0xc2b2ae35); // ring boundary
+    }
+    const key = `${n}:${h1}:${h2}`;
+    const known = crossings.get(key);
+    if (known !== undefined)
+        return known;
+    // A point repeated in a row is harmless (common in GIS data) but Turf counts it as a crossing: drop repeats.
+    const deduped = rings.map((ring) => ring.filter((p, i) => i === 0 || !samePosition(p, ring[i - 1])));
+    let result = null;
+    try {
+        const hit = kinks(toGeoJSON({ type: 'Polygon', coordinates: deduped })).features[0];
+        if (hit)
+            result = fromGeoJSON(hit.geometry).coordinates;
+    }
+    catch {
+        result = null; // degenerate rings (e.g. all repeats) are judged by the other checks, not here
+    }
+    if (crossings.size >= CROSSINGS_KEPT)
+        crossings.delete(crossings.keys().next().value);
+    crossings.set(key, result);
+    return result;
+}
+function validateParts(parts, where, each) {
+    if (!Array.isArray(parts) || parts.length === 0)
+        return invalid(`${where} needs at least one part`);
+    for (let i = 0; i < parts.length; i++) {
+        const r = each(parts[i], `${where}[${i}]`);
+        if (!r.valid)
+            return r;
+    }
+    return { valid: true };
+}
+/** Validates untrusted geometry (for example, from a provider). Never throws. */
+export function validateGeometry(value) {
+    if (typeof value !== 'object' || value === null)
+        return invalid('geometry is not an object');
+    const g = value;
+    switch (g.type) {
+        case 'Point':
+            return validatePosition(g.coordinates, 'Point.coordinates');
+        case 'LineString':
+            return validateLine(g.coordinates, 'LineString.coordinates');
+        case 'Polygon':
+            return validateRings(g.coordinates, 'Polygon');
+        case 'MultiPoint':
+            return validateParts(g.coordinates, 'MultiPoint.coordinates', (p, at) => validatePosition(p, at));
+        case 'MultiLineString':
+            return validateParts(g.coordinates, 'MultiLineString.coordinates', validateLine);
+        case 'MultiPolygon':
+            return validateParts(g.coordinates, 'MultiPolygon', validateRings);
+        case 'Circle': {
+            const c = validatePosition(g.center, 'Circle.center');
+            if (!c.valid)
+                return c;
+            if (typeof g.radiusMeters !== 'number' || !Number.isFinite(g.radiusMeters) || g.radiusMeters <= 0)
+                return invalid('Circle.radiusMeters must be a number > 0');
+            return { valid: true };
+        }
+        default:
+            return invalid(`unsupported geometry type ${JSON.stringify(g.type)}`);
+    }
+}
+export { geometryFamily } from '../core/geometry-family.js';
+const METERS_PER_DEGREE = 111_320;
+/** The positions that bound a geometry (a circle contributes its four extreme points). */
+export function positionsOf(geometry) {
+    switch (geometry.type) {
+        case 'Point':
+            return [geometry.coordinates];
+        case 'LineString':
+        case 'MultiPoint':
+            return geometry.coordinates;
+        case 'Polygon':
+        case 'MultiLineString':
+            return geometry.coordinates.flat();
+        case 'MultiPolygon':
+            return geometry.coordinates.flat(2);
+        case 'Circle': {
+            const { latitude, longitude } = geometry.center;
+            const dLat = geometry.radiusMeters / METERS_PER_DEGREE;
+            const dLon = geometry.radiusMeters / (METERS_PER_DEGREE * Math.max(0.01, Math.cos((latitude * Math.PI) / 180)));
+            return [
+                { latitude: Math.min(90, latitude + dLat), longitude },
+                { latitude: Math.max(-90, latitude - dLat), longitude },
+                { latitude, longitude: Math.min(180, longitude + dLon) },
+                { latitude, longitude: Math.max(-180, longitude - dLon) },
+            ];
+        }
+    }
+}
+export function geometryBounds(geometry) {
+    let west = Infinity;
+    let south = Infinity;
+    let east = -Infinity;
+    let north = -Infinity;
+    for (const p of positionsOf(geometry)) {
+        if (p.longitude < west)
+            west = p.longitude;
+        if (p.longitude > east)
+            east = p.longitude;
+        if (p.latitude < south)
+            south = p.latitude;
+        if (p.latitude > north)
+            north = p.latitude;
+    }
+    return { west, south, east, north };
+}
+/** Smallest bounds containing all inputs; undefined for an empty list. */
+export function unionBounds(list) {
+    if (!list.length)
+        return undefined;
+    return list.reduce((a, b) => ({ west: Math.min(a.west, b.west), south: Math.min(a.south, b.south), east: Math.max(a.east, b.east), north: Math.max(a.north, b.north) }));
+}
+export function boundsIntersect(a, b) {
+    return a.west <= b.east && a.east >= b.west && a.south <= b.north && a.north >= b.south;
+}
+export function boundsContainPosition(b, p) {
+    return p.longitude >= b.west && p.longitude <= b.east && p.latitude >= b.south && p.latitude <= b.north;
+}
+export function boundsToPolygon(b) {
+    const sw = { latitude: b.south, longitude: b.west };
+    return {
+        type: 'Polygon',
+        coordinates: [[sw, { latitude: b.south, longitude: b.east }, { latitude: b.north, longitude: b.east }, { latitude: b.north, longitude: b.west }, sw]],
+    };
+}

package/vendor/map-engine/spatial/import.d.ts

@@ -0,0 +1,27 @@
+import type { SpatialObject } from '../core/types.js';
+export interface ImportResult {
+    objects: SpatialObject[];
+    /** Features or rows that could not be used, with why (1-based row/feature numbers). */
+    skipped: Array<{
+        index: number;
+        reason: string;
+    }>;
+}
+/** A FeatureCollection, a Feature or a bare Geometry. Ids come from `idProperty`, then `feature.id`, then a counter. */
+export declare function objectsFromGeoJSON(value: unknown, options?: {
+    idProperty?: string;
+    idPrefix?: string;
+}): ImportResult;
+/** Rows with latitude/longitude columns → points. Numbers and booleans in text cells become real values. */
+export declare function objectsFromRows(rows: Array<Record<string, unknown>>, options: {
+    latitude: string;
+    longitude: string;
+    id?: string;
+    idPrefix?: string;
+}): ImportResult;
+/** Best guess at which columns hold latitude, longitude and an id. The application should let the user correct it. */
+export declare function guessCoordinateColumns(headers: string[]): {
+    latitude?: string;
+    longitude?: string;
+    id?: string;
+};

package/vendor/map-engine/spatial/import.js

@@ -0,0 +1,96 @@
+import { fromGeoJSON } from './geojson.js';
+import { validatePosition } from './geometry.js';
+const scalar = (v) => {
+    if (typeof v !== 'string')
+        return v;
+    const t = v.trim();
+    if (t === '')
+        return undefined;
+    if (/^-?\d+(\.\d+)?([eE][-+]?\d+)?$/.test(t))
+        return Number(t);
+    if (t === 'true' || t === 'false')
+        return t === 'true';
+    return t;
+};
+/** A FeatureCollection, a Feature or a bare Geometry. Ids come from `idProperty`, then `feature.id`, then a counter. */
+export function objectsFromGeoJSON(value, options = {}) {
+    const prefix = options.idPrefix ?? 'f';
+    const v = value;
+    const features = v?.type === 'FeatureCollection' && Array.isArray(v.features)
+        ? v.features
+        : v?.type === 'Feature'
+            ? [v]
+            : v && typeof v.type === 'string'
+                ? [{ type: 'Feature', geometry: v, properties: {} }]
+                : [];
+    const out = { objects: [], skipped: [] };
+    if (!features.length)
+        out.skipped.push({ index: 0, reason: 'not GeoJSON (expected a FeatureCollection, Feature or Geometry)' });
+    const seen = new Set();
+    features.forEach((f, i) => {
+        if (!f?.geometry)
+            return void out.skipped.push({ index: i + 1, reason: 'feature has no geometry' });
+        try {
+            const geometry = fromGeoJSON(f.geometry);
+            const properties = { ...(f.properties ?? {}) };
+            const raw = (options.idProperty ? properties[options.idProperty] : undefined) ?? f.id;
+            let objectId = raw !== undefined && raw !== null && raw !== '' ? String(raw) : `${prefix}-${i + 1}`;
+            if (seen.has(objectId))
+                objectId = `${objectId}~${i + 1}`;
+            seen.add(objectId);
+            out.objects.push({ objectId, geometry, properties });
+        }
+        catch (e) {
+            out.skipped.push({ index: i + 1, reason: e instanceof Error ? e.message : String(e) });
+        }
+    });
+    return out;
+}
+/** Rows with latitude/longitude columns → points. Numbers and booleans in text cells become real values. */
+export function objectsFromRows(rows, options) {
+    const out = { objects: [], skipped: [] };
+    const seen = new Set();
+    rows.forEach((row, i) => {
+        const latitude = Number(scalar(row[options.latitude]));
+        const longitude = Number(scalar(row[options.longitude]));
+        const position = { latitude, longitude };
+        const check = validatePosition(position);
+        if (!check.valid)
+            return void out.skipped.push({ index: i + 1, reason: check.reason });
+        const properties = {};
+        for (const [k, v] of Object.entries(row)) {
+            if (k === options.latitude || k === options.longitude)
+                continue;
+            const s = scalar(v);
+            if (s !== undefined)
+                properties[k] = s;
+        }
+        const raw = options.id ? row[options.id] : undefined;
+        let objectId = raw !== undefined && raw !== null && String(raw).trim() !== '' ? String(raw).trim() : `${options.idPrefix ?? 'row'}-${i + 1}`;
+        if (seen.has(objectId))
+            objectId = `${objectId}~${i + 1}`;
+        seen.add(objectId);
+        out.objects.push({ objectId, geometry: { type: 'Point', coordinates: position }, properties });
+    });
+    return out;
+}
+const LAT = ['latitude', 'lat', 'y', 'lat_deg'];
+const LON = ['longitude', 'lon', 'lng', 'long', 'x', 'lon_deg'];
+/** Real identifier columns first (exact names, then anything ending in "id"); a display name is only a last resort. */
+const ID = ['id', 'objectid', 'object_id', 'asset_id', 'assetid', 'device_id', 'deviceid', 'tag', 'asset', 'device', 'code'];
+const ID_LIKE = /(^|[\s_-])id$|[a-z]Id$|ID$/;
+/** Best guess at which columns hold latitude, longitude and an id. The application should let the user correct it. */
+export function guessCoordinateColumns(headers) {
+    const find = (names) => names.map((n) => headers.find((h) => h.trim().toLowerCase() === n)).find((h) => h !== undefined);
+    const out = {};
+    const lat = find(LAT);
+    const lon = find(LON);
+    const id = find(ID) ?? headers.find((h) => ID_LIKE.test(h.trim())) ?? find(['name', 'label', 'title']);
+    if (lat)
+        out.latitude = lat;
+    if (lon)
+        out.longitude = lon;
+    if (id)
+        out.id = id;
+    return out;
+}

package/vendor/map-engine/spatial/index.d.ts

@@ -0,0 +1,38 @@
+import { boundsContainPosition, boundsIntersect, geometryBounds, unionBounds, validateGeometry, validatePosition } from './geometry.js';
+import { fromGeoJSON, toGeoJSON } from './geojson.js';
+import { contains, distanceMeters, distanceToGeometryMeters, intersects, labelPoint, matchesRelation, within } from './operations.js';
+import { areaSquareMeters, bearingDegrees, circlePolygon, destination, ellipsePolygon, lengthMeters, measure, sectorPolygon } from './measure.js';
+/** The geometry API for engine modules and applications. Nothing outside `spatial/` imports Turf. */
+export declare const spatial: {
+    readonly validate: typeof validateGeometry;
+    readonly validatePosition: typeof validatePosition;
+    readonly bounds: typeof geometryBounds;
+    readonly unionBounds: typeof unionBounds;
+    readonly boundsIntersect: typeof boundsIntersect;
+    readonly boundsContainPosition: typeof boundsContainPosition;
+    readonly within: typeof within;
+    readonly contains: typeof contains;
+    readonly intersects: typeof intersects;
+    readonly distanceMeters: typeof distanceMeters;
+    readonly distanceToGeometryMeters: typeof distanceToGeometryMeters;
+    readonly matches: typeof matchesRelation;
+    readonly labelPoint: typeof labelPoint;
+    readonly bearingDegrees: typeof bearingDegrees;
+    readonly destination: typeof destination;
+    readonly lengthMeters: typeof lengthMeters;
+    readonly areaSquareMeters: typeof areaSquareMeters;
+    readonly measure: typeof measure;
+    readonly circlePolygon: typeof circlePolygon;
+    readonly ellipsePolygon: typeof ellipsePolygon;
+    readonly sectorPolygon: typeof sectorPolygon;
+    readonly toGeoJSON: typeof toGeoJSON;
+    readonly fromGeoJSON: typeof fromGeoJSON;
+};
+export { RBushSpatialIndex, type SpatialIndex } from './spatial-index.js';
+export { fromLngLat, toFeature, toLngLat } from './geojson.js';
+export { matchesCondition, matchesQuery, rankByRelation, validateConditions } from './query.js';
+export { boundsToPolygon, positionsOf } from './geometry.js';
+export { guessCoordinateColumns, objectsFromGeoJSON, objectsFromRows, type ImportResult } from './import.js';
+export { judgeSight, pathSamples, type SightProfilePoint, type SightResult } from './line-of-sight.js';
+export { volumeMesh, type VolumeMesh, type VolumeShape } from './volume-mesh.js';
+export type { Measurement } from './measure.js';

package/vendor/map-engine/spatial/index.js

@@ -0,0 +1,37 @@
+import { boundsContainPosition, boundsIntersect, geometryBounds, unionBounds, validateGeometry, validatePosition } from './geometry.js';
+import { fromGeoJSON, toGeoJSON } from './geojson.js';
+import { contains, distanceMeters, distanceToGeometryMeters, intersects, labelPoint, matchesRelation, within } from './operations.js';
+import { areaSquareMeters, bearingDegrees, circlePolygon, destination, ellipsePolygon, lengthMeters, measure, sectorPolygon } from './measure.js';
+/** The geometry API for engine modules and applications. Nothing outside `spatial/` imports Turf. */
+export const spatial = {
+    validate: validateGeometry,
+    validatePosition,
+    bounds: geometryBounds,
+    unionBounds,
+    boundsIntersect,
+    boundsContainPosition,
+    within,
+    contains,
+    intersects,
+    distanceMeters,
+    distanceToGeometryMeters,
+    matches: matchesRelation,
+    labelPoint,
+    bearingDegrees,
+    destination,
+    lengthMeters,
+    areaSquareMeters,
+    measure,
+    circlePolygon,
+    ellipsePolygon,
+    sectorPolygon,
+    toGeoJSON,
+    fromGeoJSON,
+};
+export { RBushSpatialIndex } from './spatial-index.js';
+export { fromLngLat, toFeature, toLngLat } from './geojson.js';
+export { matchesCondition, matchesQuery, rankByRelation, validateConditions } from './query.js';
+export { boundsToPolygon, positionsOf } from './geometry.js';
+export { guessCoordinateColumns, objectsFromGeoJSON, objectsFromRows } from './import.js';
+export { judgeSight, pathSamples } from './line-of-sight.js';
+export { volumeMesh } from './volume-mesh.js';

package/vendor/map-engine/spatial/line-of-sight.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Line of sight over the ground (phase 3E): given heights along a path, is the far end visible from the near end?
+ * Pure maths — the ground heights come from an ElevationProvider or the renderer's terrain.
+ *
+ * The Earth's curvature raises the ground between the two ends by d·(D−d)/(2·R′), with R′ the effective radius
+ * under standard atmospheric refraction (k = 0.13), so long sight lines are judged as a surveyor would.
+ */
+import type { Position } from '../core/types.js';
+/** `count` points from `from` to `to` (both ends included), evenly spaced. Fine for the ranges sight is judged over. */
+export declare function pathSamples(from: Position, to: Position, count: number): Position[];
+export interface SightProfilePoint {
+    position: Position;
+    /** Ground height (metres above sea level); null where unknown. */
+    ground: number | null;
+    /** Height of the sight line there. */
+    sight: number;
+    /** Extra ground height from the Earth's curvature there. */
+    bulge: number;
+}
+export interface SightResult {
+    visible: boolean;
+    /** The first place the ground rises above the sight line. */
+    blockedAt?: Position;
+    /** The smallest gap between the sight line and the (curved) ground; negative when blocked. */
+    clearanceMeters: number;
+    distanceMeters: number;
+    /** Samples whose ground height was unknown (they cannot block, so the answer may be optimistic). */
+    unknownSamples: number;
+    profile: SightProfilePoint[];
+}
+/**
+ * Judges a sight line. `fromHeight` and `toHeight` are the two ends' heights above sea level; `ground` holds the
+ * ground height at each of `samples` (from `pathSamples`). The two end samples never block (they are the ends).
+ */
+export declare function judgeSight(samples: Position[], ground: Array<number | null>, fromHeight: number, toHeight: number, refraction?: number): SightResult;

package/vendor/map-engine/spatial/line-of-sight.js

@@ -0,0 +1,43 @@
+import { distanceMeters } from './operations.js';
+const EARTH_RADIUS = 6_371_008.8;
+/** `count` points from `from` to `to` (both ends included), evenly spaced. Fine for the ranges sight is judged over. */
+export function pathSamples(from, to, count) {
+    const n = Math.max(2, Math.floor(count));
+    return Array.from({ length: n }, (_, i) => {
+        const t = i / (n - 1);
+        return { latitude: from.latitude + (to.latitude - from.latitude) * t, longitude: from.longitude + (to.longitude - from.longitude) * t };
+    });
+}
+/**
+ * Judges a sight line. `fromHeight` and `toHeight` are the two ends' heights above sea level; `ground` holds the
+ * ground height at each of `samples` (from `pathSamples`). The two end samples never block (they are the ends).
+ */
+export function judgeSight(samples, ground, fromHeight, toHeight, refraction = 0.13) {
+    const total = distanceMeters(samples[0], samples[samples.length - 1]);
+    const radius = EARTH_RADIUS / (1 - refraction);
+    let clearance = Infinity;
+    let blockedAt;
+    let unknown = 0;
+    const profile = samples.map((position, i) => {
+        const t = samples.length === 1 ? 0 : i / (samples.length - 1);
+        const d = total * t;
+        const bulge = (d * (total - d)) / (2 * radius);
+        const sight = fromHeight + (toHeight - fromHeight) * t;
+        const g = ground[i] ?? null;
+        if (i > 0 && i < samples.length - 1) {
+            if (g === null)
+                unknown++;
+            else {
+                const gap = sight - (g + bulge);
+                if (gap < clearance)
+                    clearance = gap;
+                if (gap < 0 && !blockedAt)
+                    blockedAt = position;
+            }
+        }
+        return { position, ground: g, sight, bulge };
+    });
+    if (clearance === Infinity)
+        clearance = Math.min(fromHeight, toHeight) - Math.max(ground[0] ?? -Infinity, ground[ground.length - 1] ?? -Infinity);
+    return { visible: !blockedAt, ...(blockedAt ? { blockedAt } : {}), clearanceMeters: clearance, distanceMeters: total, unknownSamples: unknown, profile };
+}

package/vendor/map-engine/spatial/measure.d.ts

@@ -0,0 +1,28 @@
+import type { Geometry, PolygonGeometry, Position } from '../core/types.js';
+/** Initial bearing from a to b, degrees clockwise from north [0, 360). */
+export declare function bearingDegrees(a: Position, b: Position): number;
+/** The position `meters` away from `from` along `bearing` (degrees clockwise from north). */
+export declare function destination(from: Position, bearing: number, meters: number): Position;
+/** Length of a line (or the sum of a multi-line), metres. */
+export declare function lengthMeters(geometry: Geometry): number;
+/** Area of an area geometry, square metres (holes subtracted); 0 for points and lines. */
+export declare function areaSquareMeters(geometry: Geometry): number;
+export interface Measurement {
+    /** Lines: along the line. Areas: the outline (perimeter). */
+    lengthMeters: number;
+    areaSquareMeters: number;
+    /** First point to last, degrees clockwise from north (lines with two or more points). */
+    bearingDegrees?: number;
+    /** Lines: each segment's length and bearing. */
+    segments?: Array<{
+        lengthMeters: number;
+        bearingDegrees: number;
+    }>;
+}
+export declare function measure(geometry: Geometry): Measurement;
+/** A circle as a polygon of `steps` points. */
+export declare function circlePolygon(center: Position, radiusMeters: number, steps?: number): PolygonGeometry;
+/** An ellipse as a polygon: semi-axes in metres, the major axis `orientation` degrees clockwise from north. */
+export declare function ellipsePolygon(center: Position, semiMajor: number, semiMinor: number, orientation?: number, steps?: number): PolygonGeometry;
+/** A sector (pie slice) from `near` to `far` metres between two bearings, as a polygon. */
+export declare function sectorPolygon(center: Position, fromBearing: number, toBearing: number, near: number, far: number, steps?: number): PolygonGeometry;